Instrument Neutral Distributed Interface INDI  0.9.9
indidevapi.h
Go to the documentation of this file.
1 #if 0
2  INDI
3  Copyright (C) 2003-2006 Elwood C. Downey
4 
5  Modified by Jasem Mutlaq (2003-2015)
6 
7  This library is free software; you can redistribute it and/or
8  modify it under the terms of the GNU Lesser General Public
9  License as published by the Free Software Foundation; either
10  version 2.1 of the License, or (at your option) any later version.
11 
12  This library is distributed in the hope that it will be useful,
13  but WITHOUT ANY WARRANTY; without even the implied warranty of
14  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15  Lesser General Public License for more details.
16 
17  You should have received a copy of the GNU Lesser General Public
18  License along with this library; if not, write to the Free Software
19  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 
21 #endif
22 
23 #ifndef INDI_DEVAPI_H
24 #define INDI_DEVAPI_H
25 
90 /*******************************************************************************
91  * get the data structures
92  */
93 
94 #include "indiapi.h"
95 #include "lilxml.h"
96 
97 /*******************************************************************************
98  *******************************************************************************
99  *
100  * Functions the INDI device driver framework defines which the Driver may call
101  *
102  *******************************************************************************
103  *******************************************************************************
104  */
105 
106 #ifdef __cplusplus
107 extern "C" {
108 #endif
109 
129 
134 extern void IDDefText (const ITextVectorProperty *t, const char *msg, ...)
135 #ifdef __GNUC__
136  __attribute__ ( ( format( printf, 2, 3 ) ) )
137 #endif
138 ;
139 
144 extern void IDDefNumber (const INumberVectorProperty *n, const char *msg, ...)
145 #ifdef __GNUC__
146  __attribute__ ( ( format( printf, 2, 3 ) ) )
147 #endif
148 ;
149 
154 extern void IDDefSwitch (const ISwitchVectorProperty *s, const char *msg, ...)
155 #ifdef __GNUC__
156  __attribute__ ( ( format( printf, 2, 3 ) ) )
157 #endif
158 ;
159 
164 extern void IDDefLight (const ILightVectorProperty *l, const char *msg, ...)
165 #ifdef __GNUC__
166  __attribute__ ( ( format( printf, 2, 3 ) ) )
167 #endif
168 ;
169 
174 extern void IDDefBLOB (const IBLOBVectorProperty *b, const char *msg, ...)
175 #ifdef __GNUC__
176  __attribute__ ( ( format( printf, 2, 3 ) ) )
177 #endif
178 ;
179 
180 
187 
192 extern void IDSetText (const ITextVectorProperty *t, const char *msg, ...)
193 #ifdef __GNUC__
194  __attribute__ ( ( format( printf, 2, 3 ) ) )
195 #endif
196 ;
197 
202 extern void IDSetNumber (const INumberVectorProperty *n, const char *msg, ...)
203 #ifdef __GNUC__
204  __attribute__ ( ( format( printf, 2, 3 ) ) )
205 #endif
206 ;
207 
212 extern void IDSetSwitch (const ISwitchVectorProperty *s, const char *msg, ...)
213 #ifdef __GNUC__
214  __attribute__ ( ( format( printf, 2, 3 ) ) )
215 #endif
216 ;
217 
222 extern void IDSetLight (const ILightVectorProperty *l, const char *msg, ...)
223 #ifdef __GNUC__
224  __attribute__ ( ( format( printf, 2, 3 ) ) )
225 #endif
226 ;
227 
232 extern void IDSetBLOB (const IBLOBVectorProperty *b, const char *msg, ...)
233 #ifdef __GNUC__
234  __attribute__ ( ( format( printf, 2, 3 ) ) )
235 #endif
236 ;
237 
244 
245 
253 extern void IDMessage (const char *dev, const char *msg, ...)
254 #ifdef __GNUC__
255  __attribute__ ( ( format( printf, 2, 3 ) ) )
256 #endif
257 ;
258 
265 extern void IDDelete (const char *dev, const char *name, const char *msg, ...)
266 #ifdef __GNUC__
267  __attribute__ ( ( format( printf, 3, 4 ) ) )
268 #endif
269 ;
270 
277 extern void IDLog (const char *msg, ...)
278 #ifdef __GNUC__
279  __attribute__ ( ( format( printf, 1, 2 ) ) )
280 #endif
281 ;
282 
290 
291 
294 typedef enum
295 {
299 } BLOBHandling;
300 
305 extern void IDSnoopDevice (const char *snooped_device, const char *snooped_property);
306 
311 extern void IDSnoopBLOBs (const char *snooped_device, BLOBHandling bh);
312 
321 
322  /* signature of a callback, timout caller and work procedure function */
323 
326 typedef void (IE_CBF) (int readfiledes, void *userpointer);
327 
330 typedef void (IE_TCF) (void *userpointer);
331 
334 typedef void (IE_WPF) (void *userpointer);
335 
336 /* functions to add and remove callbacks, timers and work procedures */
337 
345 extern int IEAddCallback (int readfiledes, IE_CBF *fp, void *userpointer);
346 
351 extern void IERmCallback (int callbackid);
352 
362 extern int IEAddTimer (int millisecs, IE_TCF *fp, void *userpointer);
363 
368 extern void IERmTimer (int timerid);
369 
376 extern int IEAddWorkProc (IE_WPF *fp, void *userpointer);
377 
382 extern void IERmWorkProc (int workprocid);
383 
384 /* wait in-line for a flag to set, presumably by another event function */
385 
386 extern int IEDeferLoop (int maxms, int *flagp);
387 extern int IEDeferLoop0 (int maxms, int *flagp);
388 
402 
403 
410 extern IText *IUFindText (const ITextVectorProperty *tvp, const char *name);
411 
418 extern INumber *IUFindNumber(const INumberVectorProperty *nvp, const char *name);
419 
426 extern ISwitch *IUFindSwitch(const ISwitchVectorProperty *svp, const char *name);
427 
434 extern ILight *IUFindLight(const ILightVectorProperty *lvp, const char *name);
435 
442 extern IBLOB *IUFindBLOB(const IBLOBVectorProperty *bvp, const char *name);
443 
451 extern ISwitch *IUFindOnSwitch (const ISwitchVectorProperty *sp);
452 
460 extern int IUFindIndex (const char *needle, char **hay, unsigned int n);
461 
462 
471 extern int IUFindOnSwitchIndex (const ISwitchVectorProperty *sp);
472 
477 extern void IUResetSwitch(ISwitchVectorProperty *svp);
478 
487 extern int IUUpdateSwitch(ISwitchVectorProperty *svp, ISState *states, char *names[], int n);
488 
497 extern int IUUpdateNumber(INumberVectorProperty *nvp, double values[], char *names[], int n);
498 
507 extern int IUUpdateText(ITextVectorProperty *tvp, char * texts[], char *names[], int n);
508 
520 extern int IUUpdateBLOB(IBLOBVectorProperty *bvp, int sizes[], int blobsizes[], char *blobs[], char *formats[], char *names[], int n);
521 
530 extern int IUSaveBLOB(IBLOB *bp, int size, int blobsize, char *blob, char *format);
531 
535 extern void IUUpdateMinMax(const INumberVectorProperty *nvp);
536 
541 extern void IUSaveText (IText *tp, const char *newtext);
542 
549 extern void IUFillSwitch(ISwitch *sp, const char *name, const char * label, ISState s);
550 
557 extern void IUFillLight(ILight *lp, const char *name, const char * label, IPState s);
558 
569 extern void IUFillNumber(INumber *np, const char *name, const char * label, const char *format, double min, double max, double step, double value);
570 
577 extern void IUFillText(IText *tp, const char *name, const char * label, const char *initialText);
578 
585 extern void IUFillBLOB(IBLOB *bp, const char *name, const char * label, const char *format);
586 
600 extern void IUFillSwitchVector(ISwitchVectorProperty *svp, ISwitch *sp, int nsp, const char * dev, const char *name, const char *label, const char *group, IPerm p, ISRule r, double timeout, IPState s);
601 
612 extern void IUFillLightVector(ILightVectorProperty *lvp, ILight *lp, int nlp, const char * dev, const char *name, const char *label, const char *group, IPState s);
613 
626 extern void IUFillNumberVector(INumberVectorProperty *nvp, INumber *np, int nnp, const char * dev, const char *name, const char *label, const char* group, IPerm p, double timeout, IPState s);
627 
640 extern void IUFillTextVector(ITextVectorProperty *tvp, IText *tp, int ntp, const char * dev, const char *name, const char *label, const char* group, IPerm p, double timeout, IPState s);
641 
654 extern void IUFillBLOBVector(IBLOBVectorProperty *bvp, IBLOB *bp, int nbp, const char * dev, const char *name, const char *label, const char* group, IPerm p, double timeout, IPState s);
655 
656 
662 extern int IUSnoopNumber (XMLEle *root, INumberVectorProperty *nvp);
663 
669 extern int IUSnoopText (XMLEle *root, ITextVectorProperty *tvp);
670 
676 extern int IUSnoopLight (XMLEle *root, ILightVectorProperty *lvp);
677 
683 extern int IUSnoopSwitch (XMLEle *root, ISwitchVectorProperty *svp);
684 
690 extern int IUSnoopBLOB (XMLEle *root, IBLOBVectorProperty *bvp);
691 
694 /*******************************************************************************
695  *******************************************************************************
696  *
697  * Functions the INDI Device Driver framework calls which the Driver must
698  * define.
699  *
700  *******************************************************************************
701  *******************************************************************************
702  */
703 
704 
705 
714 
728 extern void ISGetProperties (const char *dev);
729 
730 
739 extern void ISNewText (const char *dev, const char *name, char *texts[],
740  char *names[], int n);
741 
750 extern void ISNewNumber (const char *dev, const char *name, double *doubles,
751  char *names[], int n);
752 
761 extern void ISNewSwitch (const char *dev, const char *name, ISState *states,
762  char *names[], int n);
763 
777 extern void ISNewBLOB (const char *dev, const char *name, int sizes[], int blobsizes[], char *blobs[], char *formats[], char *names[], int n);
778 
783 extern void ISSnoopDevice (XMLEle *root);
784 
787 /* Handy readability macro to avoid unused variables warnings */
788 #define INDI_UNUSED(x) (void) x
789 
799 extern int crackDN (XMLEle *root, char **dev, char **name, char msg[]);
800 
806 extern int crackIPState (const char *str, IPState *ip);
807 
813 extern int crackISState (const char *str, ISState *ip);
814 
820 extern int crackIPerm (const char *str, IPerm *ip);
821 
827 extern int crackISRule (const char *str, ISRule *ip);
828 
830 extern const char *pstateStr(IPState s);
832 extern const char *sstateStr(ISState s);
834 extern const char *ruleStr(ISRule r);
836 extern const char *permStr(IPerm p);
837 
838 extern void xmlv1(void);
839 
840 #ifdef __cplusplus
841 }
842 #endif
843 
844 #endif
void IUSaveText(IText *tp, const char *newtext)
Function to reliably save new text in a IText.
Definition: indicom.c:1181
void IUResetSwitch(ISwitchVectorProperty *svp)
Reset all switches in a switch vector property to OFF.
Definition: indicom.c:1171
const char * pstateStr(IPState s)
Definition: indicom.c:947
Light vector property descriptor.
Definition: indiapi.h:332
int IUSnoopText(XMLEle *root, ITextVectorProperty *tvp)
Update a snooped text vector property from the given XML root element.
Definition: indidriver.c:616
void IUFillNumberVector(INumberVectorProperty *nvp, INumber *np, int nnp, const char *dev, const char *name, const char *label, const char *group, IPerm p, double timeout, IPState s)
Assign attributes for a number vector property. The vector's auxiliary elements will be set to NULL...
Definition: indidriver.c:502
void IDSetText(const ITextVectorProperty *t, const char *msg,...)
Tell client to update an existing text vector property.
Definition: indidriver.c:1683
ILight * IUFindLight(const ILightVectorProperty *lvp, const char *name)
Find an ILight member in a vector Light property.
Definition: indicom.c:1119
void IDSetSwitch(const ISwitchVectorProperty *s, const char *msg,...)
Tell client to update an existing switch vector property.
Definition: indidriver.c:1763
int crackISRule(const char *str, ISRule *ip)
Extract switch rule (OneOfMany, OnlyOne..etc) from the supplied string.
Definition: indicom.c:996
IPState
Property state.
Definition: indiapi.h:115
One light descriptor.
Definition: indiapi.h:321
int IEAddWorkProc(IE_WPF *fp, void *userpointer)
Add a new work procedure, fp, to be called with ud when nothing else to do.
Definition: indidriver.c:183
void IDDefNumber(const INumberVectorProperty *n, const char *msg,...)
Tell client to create a number number property.
Definition: indidriver.c:1456
void IDMessage(const char *dev, const char *msg,...)
Function Drivers call to send log messages to Clients.
Definition: indidriver.c:1235
int IUUpdateSwitch(ISwitchVectorProperty *svp, ISState *states, char *names[], int n)
Update all switches in a switch vector property.
Definition: indidriver.c:209
int IUUpdateText(ITextVectorProperty *tvp, char *texts[], char *names[], int n)
Update all text members in a text vector property.
Definition: indidriver.c:300
int IEAddTimer(int millisecs, IE_TCF *fp, void *userpointer)
Register a new timer function, fp, to be called with ud as argument after ms.
Definition: indidriver.c:171
One number descriptor.
Definition: indiapi.h:224
int IUUpdateNumber(INumberVectorProperty *nvp, double values[], char *names[], int n)
Update all numbers in a number vector property.
Definition: indidriver.c:263
int IUSnoopLight(XMLEle *root, ILightVectorProperty *lvp)
Update a snooped light vector property from the given XML root element.
Definition: indidriver.c:653
One Blob (Binary Large Object) descriptor.
Definition: indiapi.h:356
int crackIPerm(const char *str, IPerm *ip)
Extract property permission state (RW, RO, WO) from the supplied string.
Definition: indicom.c:987
int IUSaveBLOB(IBLOB *bp, int size, int blobsize, char *blob, char *format)
Function to save blob metadata in the corresponding blob.
Definition: indidriver.c:358
void IDDefBLOB(const IBLOBVectorProperty *b, const char *msg,...)
Tell client to create a BLOB vector property.
Definition: indidriver.c:1626
void ISSnoopDevice(XMLEle *root)
Function defined by Drivers that is called when another Driver it is snooping (by having previously c...
Definition: dome.cpp:79
void IUUpdateMinMax(const INumberVectorProperty *nvp)
Function to update the min and max elements of a number in the client.
Definition: indidriver.c:1891
void IERmTimer(int timerid)
Remove the timer with the given timerid, as returned from IEAddTimer.
Definition: indidriver.c:177
void IDSetNumber(const INumberVectorProperty *n, const char *msg,...)
Tell client to update an existing number vector property.
Definition: indidriver.c:1723
void( IE_CBF)(int readfiledes, void *userpointer)
Signature of a callback.
Definition: indidevapi.h:326
Switch vector property descriptor.
Definition: indiapi.h:291
Namespace to encapsulate INDI client, drivers, and mediator classes. Developers can subclass the base...
void IDSnoopBLOBs(const char *snooped_device, BLOBHandling bh)
Function a Driver calls to control whether they will receive BLOBs from snooped devices.
Definition: indidriver.c:137
void ISNewText(const char *dev, const char *name, char *texts[], char *names[], int n)
Update the value of an existing text vector property.
Definition: dome.cpp:55
void ISNewNumber(const char *dev, const char *name, double *doubles, char *names[], int n)
Update the value of an existing number vector property.
const char * permStr(IPerm p)
Definition: indicom.c:1034
int IUSnoopNumber(XMLEle *root, INumberVectorProperty *nvp)
Update a snooped number vector property from the given XML root element.
Definition: indidriver.c:578
One switch descriptor.
Definition: indiapi.h:280
IText * IUFindText(const ITextVectorProperty *tvp, const char *name)
Find an IText member in a vector text property.
Definition: indicom.c:1080
void IUFillText(IText *tp, const char *name, const char *label, const char *initialText)
Assign attributes for a text property. The text's auxiliary elements will be set to NULL...
Definition: indidriver.c:419
void ISNewSwitch(const char *dev, const char *name, ISState *states, char *names[], int n)
Update the value of an existing switch vector property.
Definition: dome.cpp:49
void IUFillBLOB(IBLOB *bp, const char *name, const char *label, const char *format)
Assign attributes for a BLOB property. The BLOB's data and auxiliary elements will be set to NULL...
Definition: indidriver.c:439
void IUFillSwitch(ISwitch *sp, const char *name, const char *label, ISState s)
Assign attributes for a switch property. The switch's auxiliary elements will be set to NULL...
Definition: indidriver.c:367
BLOB (Binary Large Object) vector property descriptor.
Definition: indiapi.h:379
BLOBHandling
How drivers handle BLOBs incoming from snooping drivers.
Definition: indidevapi.h:294
Constants and Data structure definitions for the interface to the reference INDI C API implementation...
IBLOB * IUFindBLOB(const IBLOBVectorProperty *bvp, const char *name)
Find an IBLOB member in a vector BLOB property.
Definition: indicom.c:1132
void IERmCallback(int callbackid)
Remove a callback function.
Definition: indidriver.c:165
int crackDN(XMLEle *root, char **dev, char **name, char msg[])
Extract dev and name attributes from an XML element.
Definition: indicom.c:1057
const char * ruleStr(ISRule r)
Definition: indicom.c:1020
void IUFillNumber(INumber *np, const char *name, const char *label, const char *format, double min, double max, double step, double value)
Assign attributes for a number property. The number's auxiliary elements will be set to NULL...
Definition: indidriver.c:398
void( IE_WPF)(void *userpointer)
Signature of a work procedure function.
Definition: indidevapi.h:334
int IUSnoopSwitch(XMLEle *root, ISwitchVectorProperty *svp)
Update a snooped switch vector property from the given XML root element.
Definition: indidriver.c:693
int crackISState(const char *str, ISState *ip)
Extract switch state (On or Off) from the supplied string.
Definition: indicom.c:978
INumber * IUFindNumber(const INumberVectorProperty *nvp, const char *name)
Find an INumber member in a number text property.
Definition: indicom.c:1093
void IDSnoopDevice(const char *snooped_device, const char *snooped_property)
Function a Driver calls to snoop on another Device. Snooped messages will then arrive via ISSnoopDevi...
Definition: indidriver.c:120
void ISGetProperties(const char *dev)
Get Device Properties.
Definition: dome.cpp:43
int IUFindOnSwitchIndex(const ISwitchVectorProperty *sp)
Returns the index of first ON switch it finds in the vector switch property.
Definition: indicom.c:1159
Number vector property descriptor.
Definition: indiapi.h:252
int crackIPState(const char *str, IPState *ip)
Extract property state (Idle, OK, Busy, Alert) from the supplied string.
Definition: indicom.c:964
int IUSnoopBLOB(XMLEle *root, IBLOBVectorProperty *bvp)
Update a snooped BLOB vector property from the given XML root element.
Definition: indidriver.c:733
One text descriptor.
Definition: indiapi.h:178
void IDSetBLOB(const IBLOBVectorProperty *b, const char *msg,...)
Tell client to update an existing BLOB vector property.
Definition: indidriver.c:1840
void IDDefLight(const ILightVectorProperty *l, const char *msg,...)
Tell client to create a light vector property.
Definition: indidriver.c:1585
void IERmWorkProc(int workprocid)
Remove a work procedure.
Definition: indidriver.c:189
void IDSetLight(const ILightVectorProperty *l, const char *msg,...)
Tell client to update an existing light vector property.
Definition: indidriver.c:1803
int IEAddCallback(int readfiledes, IE_CBF *fp, void *userpointer)
Register a new callback, fp, to be called with userpointer as argument when readfiledes is ready...
Definition: indidriver.c:159
void( IE_TCF)(void *userpointer)
Signature of a timeout caller.
Definition: indidevapi.h:330
int IUFindIndex(const char *needle, char **hay, unsigned int n)
Returns the index of the string in a string array.
Definition: indidriver.c:1936
void ISNewBLOB(const char *dev, const char *name, int sizes[], int blobsizes[], char *blobs[], char *formats[], char *names[], int n)
Update data of an existing blob vector property.
Definition: dome.cpp:67
void IDLog(const char *msg,...)
Function Drivers call to log a message locally.
Definition: indicom.c:224
void IUFillBLOBVector(IBLOBVectorProperty *bvp, IBLOB *bp, int nbp, const char *dev, const char *name, const char *label, const char *group, IPerm p, double timeout, IPState s)
Assign attributes for a BLOB vector property. The vector's auxiliary elements will be set to NULL...
Definition: indidriver.c:546
IPerm
Permission hint, with respect to client.
Definition: indiapi.h:136
ISState
Switch state.
Definition: indiapi.h:106
void IUFillSwitchVector(ISwitchVectorProperty *svp, ISwitch *sp, int nsp, const char *dev, const char *name, const char *label, const char *group, IPerm p, ISRule r, double timeout, IPState s)
Assign attributes for a switch vector property. The vector's auxiliary elements will be set to NULL...
Definition: indidriver.c:460
A little DOM-style library to handle parsing and processing an XML file.
ISwitch * IUFindSwitch(const ISwitchVectorProperty *svp, const char *name)
Find an ISwitch member in a vector switch property.
Definition: indicom.c:1106
ISwitch * IUFindOnSwitch(const ISwitchVectorProperty *sp)
Returns the first ON switch it finds in the vector switch property.
Definition: indicom.c:1147
const char * sstateStr(ISState s)
Definition: indicom.c:1007
void IUFillTextVector(ITextVectorProperty *tvp, IText *tp, int ntp, const char *dev, const char *name, const char *label, const char *group, IPerm p, double timeout, IPState s)
Assign attributes for a text vector property. The vector's auxiliary elements will be set to NULL...
Definition: indidriver.c:525
void IDDelete(const char *dev, const char *name, const char *msg,...)
Function Drivers call to inform Clients a Property is no longer available, or the entire device is go...
Definition: indidriver.c:93
Text vector property descriptor.
Definition: indiapi.h:196
void IUFillLightVector(ILightVectorProperty *lvp, ILight *lp, int nlp, const char *dev, const char *name, const char *label, const char *group, IPState s)
Assign attributes for a light vector property. The vector's auxiliary elements will be set to NULL...
Definition: indidriver.c:482
int IUUpdateBLOB(IBLOBVectorProperty *bvp, int sizes[], int blobsizes[], char *blobs[], char *formats[], char *names[], int n)
Update all BLOB members in a BLOB vector property.
Definition: indidriver.c:330
ISRule
Switch vector rule hint.
Definition: indiapi.h:126
void IDDefSwitch(const ISwitchVectorProperty *s, const char *msg,...)
Tell client to create a switch vector property.
Definition: indidriver.c:1525
void IDDefText(const ITextVectorProperty *t, const char *msg,...)
Tell client to create a text vector property.
Definition: indidriver.c:1398
void IUFillLight(ILight *lp, const char *name, const char *label, IPState s)
Assign attributes for a light property. The light's auxiliary elements will be set to NULL...
Definition: indidriver.c:382