moved kdeaccessibility kdeaddons kdeadmin kdeartwork kdebindings kdeedu kdegames...
[kdeedu.git] / kstars / kstars / indi / indidevapi.h
blob15f87c6180af0aeb33e84ba3dc77339e5f842c77
1 #if 0
2 INDI
3 Copyright (C) 2003 Elwood C. Downey
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
15 You should have received a copy of the GNU Lesser General Public
16 License along with this library; if not, write to the Free Software
17 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 #endif
21 #ifndef INDI_DEVAPI_H
22 #define INDI_DEVAPI_H
24 /** \file indidevapi.h
25 \brief Interface to the reference INDI C API device implementation on the Device Driver side.
26 \author Elwood C. Downey
27 \author Jasem Mutlaq
29 This file is divided into two main sections:\n
30 <ol><li> Functions the INDI device driver framework defines which the Driver may
31 call:</li>
33 <ul><li>IDxxx functions to send messages to an INDI client.</li>
34 <li>IExxx functions to implement the event driven model.</li>
35 <li>IUxxx functions to perform handy utility functions.</li></ul>
37 <li>Functions the INDI device driver framework calls which the Driver must
38 define:</li>
40 <ul><li>ISxxx to respond to messages from a Client.</li></ul></ol>
44 /*******************************************************************************
45 * get the data structures
48 #include "indiapi.h"
50 /*******************************************************************************
51 *******************************************************************************
53 * Functions the INDI device driver framework defines which the Driver calls
55 *******************************************************************************
56 *******************************************************************************
59 #ifdef __cplusplus
60 extern "C" {
61 #endif
63 /**
64 * \defgroup d2cFunctions Functions Drivers call to define their Properties to Clients.
66 /*@{*/
68 /** \brief Tell client to create a text vector property.
69 \param t pointer to the vector text property to be defined.
70 \param msg message in printf style to send to the client. May be NULL.
72 extern void IDDefText (const ITextVectorProperty *t, const char *msg, ...)
73 #ifdef __GNUC__
74 __attribute__ ( ( format( printf, 2, 3 ) ) )
75 #endif
78 /** \brief Tell client to create a number number property.
79 \param n pointer to the vector number property to be defined.
80 \param msg message in printf style to send to the client. May be NULL.
82 extern void IDDefNumber (const INumberVectorProperty *n, const char *msg, ...)
83 #ifdef __GNUC__
84 __attribute__ ( ( format( printf, 2, 3 ) ) )
85 #endif
88 /** \brief Tell client to create a switch vector property.
89 \param s pointer to the vector switch property to be defined.
90 \param msg message in printf style to send to the client. May be NULL.
92 extern void IDDefSwitch (const ISwitchVectorProperty *s, const char *msg, ...)
93 #ifdef __GNUC__
94 __attribute__ ( ( format( printf, 2, 3 ) ) )
95 #endif
98 /** \brief Tell client to create a light vector property.
99 \param l pointer to the vector light property to be defined.
100 \param msg message in printf style to send to the client. May be NULL.
102 extern void IDDefLight (const ILightVectorProperty *l, const char *msg, ...)
103 #ifdef __GNUC__
104 __attribute__ ( ( format( printf, 2, 3 ) ) )
105 #endif
108 /** \brief Tell client to create a BLOB vector property.
109 \param l pointer to the vector BLOB property to be defined.
110 \param msg message in printf style to send to the client. May be NULL.
112 extern void IDDefBLOB (const IBLOBVectorProperty *b, const char *msg, ...)
113 #ifdef __GNUC__
114 __attribute__ ( ( format( printf, 2, 3 ) ) )
115 #endif
119 /*@}*/
122 * \defgroup d2cuFunctions Functions Drivers call to tell Clients of new values for existing Properties.
124 /*@{*/
126 /** \brief Tell client to update an existing text vector property.
127 \param t pointer to the vector text property.
128 \param msg message in printf style to send to the client. May be NULL.
130 extern void IDSetText (const ITextVectorProperty *t, const char *msg, ...)
131 #ifdef __GNUC__
132 __attribute__ ( ( format( printf, 2, 3 ) ) )
133 #endif
136 /** \brief Tell client to update an existing number vector property.
137 \param n pointer to the vector number property.
138 \param msg message in printf style to send to the client. May be NULL.
140 extern void IDSetNumber (const INumberVectorProperty *n, const char *msg, ...)
141 #ifdef __GNUC__
142 __attribute__ ( ( format( printf, 2, 3 ) ) )
143 #endif
146 /** \brief Tell client to update an existing switch vector property.
147 \param s pointer to the vector switch property.
148 \param msg message in printf style to send to the client. May be NULL.
150 extern void IDSetSwitch (const ISwitchVectorProperty *s, const char *msg, ...)
151 #ifdef __GNUC__
152 __attribute__ ( ( format( printf, 2, 3 ) ) )
153 #endif
156 /** \brief Tell client to update an existing light vector property.
157 \param l pointer to the vector light property.
158 \param msg message in printf style to send to the client. May be NULL.
160 extern void IDSetLight (const ILightVectorProperty *l, const char *msg, ...)
161 #ifdef __GNUC__
162 __attribute__ ( ( format( printf, 2, 3 ) ) )
163 #endif
166 /** \brief Tell client to update an existing BLOB vector property.
167 \param l pointer to the vector BLOB property.
168 \param msg message in printf style to send to the client. May be NULL.
170 extern void IDSetBLOB (const IBLOBVectorProperty *b, const char *msg, ...)
171 #ifdef __GNUC__
172 __attribute__ ( ( format( printf, 2, 3 ) ) )
173 #endif
176 /*@}*/
179 /** \brief Function Drivers call to send log messages to Clients.
181 If dev is specified the Client shall associate the message with that device; if dev is NULL the Client shall treat the message as generic from no specific Device.
183 \param dev device name
184 \param msg message in printf style to send to the client.
186 extern void IDMessage (const char *dev, const char *msg, ...)
187 #ifdef __GNUC__
188 __attribute__ ( ( format( printf, 2, 3 ) ) )
189 #endif
192 /** \brief Function Drivers call to inform Clients a Property is no longer available, or the entire device is gone if name is NULL.
194 \param dev device name. If device name is NULL, the entire device will be deleted.
195 \param name property name to be deleted.
196 \param msg message in printf style to send to the client.
198 extern void IDDelete (const char *dev, const char *name, const char *msg, ...)
199 #ifdef __GNUC__
200 __attribute__ ( ( format( printf, 3, 4 ) ) )
201 #endif
204 /** \brief Function Drivers call to log a message locally.
206 The message is not sent to any Clients.
208 \param msg message in printf style to send to the client.
210 extern void IDLog (const char *msg, ...)
211 #ifdef __GNUC__
212 __attribute__ ( ( format( printf, 1, 2 ) ) )
213 #endif
217 * \defgroup deventFunctions Functions Drivers call to register with the INDI event utilities.
219 Callbacks are called when a read on a file descriptor will not block. Timers are called once after a specified interval. Workprocs are called when there is nothing else to do. The "Add" functions return a unique id for use with their corresponding "Rm" removal function. An arbitrary pointer may be specified when a function is registered which will be stored and forwarded unchanged when the function is later invoked.
221 /*@{*/
223 /* signature of a callback, timout caller and work procedure function */
225 /** \typedef IE_CBF Signature of a callback. */
226 typedef void (IE_CBF) (int readfiledes, void *userpointer);
227 /** \typedef IE_CBF Signature of a timeout caller. */
228 typedef void (IE_TCF) (void *userpointer);
229 /** \typedef IE_CBF Signature of a work procedure function. */
230 typedef void (IE_WPF) (void *userpointer);
232 /* functions to add and remove callbacks, timers and work procedures */
234 /** \brief Register a new callback, \e fp, to be called with \e userpointer as argument when \e readfiledes is ready.
236 * \param readfiledes file descriptor.
237 * \param fp a pointer to the callback function.
238 * \param userpointer a pointer to be passed to the callback function when called.
239 * \return a unique callback id for use with IERmCallback().
241 extern int IEAddCallback (int readfiledes, IE_CBF *fp, void *userpointer);
243 /** \brief Remove a callback function.
245 * \param callbackid the callback ID returned from IEAddCallback()
247 extern void IERmCallback (int callbackid);
249 /** \brief Register a new timer function, \e fp, to be called with \e ud as argument after \e ms.
251 Add to list in order of decreasing time from epoch, ie, last entry runs soonest. The timer will only invoke the callback function \b once. You need to call addTimer again if you want to repeat the process.
253 * \param millisecs timer period in milliseconds.
254 * \param fp a pointer to the callback function.
255 * \param userpointer a pointer to be passed to the callback function when called.
256 * \return a unique id for use with IERmTimer().
258 extern int IEAddTimer (int millisecs, IE_TCF *fp, void *userpointer);
260 /** \brief Remove the timer with the given \e timerid, as returned from IEAddTimer.
262 * \param timerid the timer callback ID returned from IEAddTimer().
264 extern void IERmTimer (int timerid);
266 /** \brief Add a new work procedure, fp, to be called with ud when nothing else to do.
268 * \param fp a pointer to the work procedure callback function.
269 * \param userpointer a pointer to be passed to the callback function when called.
270 * \return a unique id for use with IERmWorkProc().
272 extern int IEAddWorkProc (IE_WPF *fp, void *userpointer);
274 /** \brief Remove the work procedure with the given \e workprocid, as returned from IEAddWorkProc().
276 * \param workprocid the work procedure callback ID returned from IEAddWorkProc().
278 extern void IERmWorkProc (int workprocid);
280 /*@}*/
283 * \defgroup dutilFunctions Functions Drivers call to perform handy utility functions.
285 These do not communicate with the Client in any way.
287 /*@{*/
290 /** \brief Find an IText member in a vector text property.
292 * \param tp a pointer to a text vector property.
293 * \param name the name of the member to search for.
294 * \return a pointer to an IText member on match, or NULL if nothing is found.
296 extern IText *IUFindText (const ITextVectorProperty *tp, const char *name);
298 /** \brief Find an INumber member in a number text property.
300 * \param tp a pointer to a number vector property.
301 * \param name the name of the member to search for.
302 * \return a pointer to an INumber member on match, or NULL if nothing is found.
304 extern INumber *IUFindNumber(const INumberVectorProperty *tp, const char *name);
306 /** \brief Find an ISwitch member in a vector switch property.
308 * \param tp a pointer to a switch vector property.
309 * \param name the name of the member to search for.
310 * \return a pointer to an ISwitch member on match, or NULL if nothing is found.
312 extern ISwitch *IUFindSwitch(const ISwitchVectorProperty *tp, const char *name);
314 /** \brief Returns the first ON switch it finds in the vector switch property.
316 * \note This is only valid for ISR_1OFMANY mode. That is, when only one switch out of many is allowed to be ON. Do not use this function if you can have multiple ON switches in the same vector property.
318 * \param tp a pointer to a switch vector property.
319 * \return a pointer to the \e first ON ISwitch member if found. If all switches are off, NULL is returned.
321 extern ISwitch *IUFindOnSwitch (const ISwitchVectorProperty *tp);
323 /** \brief Reset all switches in a switch vector property to OFF.
325 * \param svp a pointer to a switch vector property.
327 extern void IUResetSwitches(const ISwitchVectorProperty *svp);
329 /** \brief Update all switches in a switch vector property.
331 * \param svp a pointer to a switch vector property.
332 * \param states the states of the new ISwitch members.
333 * \param names the names of the ISwtich members to update.
334 * \param n the number of ISwitch members to update.
335 * \return 0 if update successful, -1 otherwise.
337 extern int IUUpdateSwitches(ISwitchVectorProperty *svp, ISState *states, char *names[], int n);
339 /** \brief Update all numbers in a number vector property.
341 * \param nvp a pointer to a number vector property.
342 * \param values the states of the new INumber members.
343 * \param names the names of the INumber members to update.
344 * \param n the number of INumber members to update.
345 * \return 0 if update successful, -1 otherwise. Update will fail if values are out of scope, or in case of property name mismatch.
347 extern int IUUpdateNumbers(INumberVectorProperty *nvp, double values[], char *names[], int n);
349 /** \brief Function to update the min and max elements of a number in the client
350 \param tp pointer to an INumberVectorProperty.
352 extern void IUUpdateMinMax(INumberVectorProperty *nvp);
354 /** \brief Function to reliably save new text in a IText.
355 \param tp pointer to an IText member.
356 \param newtext the new text to be saved
358 extern void IUSaveText (IText *tp, const char *newtext);
360 extern void fillSwitch(ISwitch *sp, const char *name, const char * label, ISState s);
361 extern void fillNumber(INumber *np, const char *name, const char * label, const char *format, double min, double max, double step, double value);
362 extern void fillText(IText *tp, const char *name, const char * label, const char *initialText);
364 extern void fillSwitchVector(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);
365 extern void fillNumberVector(INumberVectorProperty *nvp, INumber *np, int nnp, const char * dev, const char *name, const char *label, const char* group, IPerm p, double timeout, IPState s);
366 extern void fillTextVector(ITextVectorProperty *tvp, IText *tp, int ntp, const char * dev, const char *name, const char *label, const char* group, IPerm p, double timeout, IPState s);
368 /*@}*/
370 /*******************************************************************************
371 *******************************************************************************
373 * Functions the INDI Device Driver framework calls which the Driver must
374 * define.
376 *******************************************************************************
377 *******************************************************************************
381 /** \brief Function defined by Drivers that is called when a Client asks for the definitions of all Properties this Driver supports for the given device.
382 \param dev the name of the device.
384 extern void ISGetProperties (const char *dev);
388 * \defgroup dcuFunctions Functions defined by Drivers that are called when a Client wishes to set different values named members of the given vector Property.
390 The values and their names are parallel arrays of n elements each.
392 /*@{*/
394 /** \brief Update the value of an existing text vector property.
395 \param dev the name of the device.
396 \param name the name of the text vector property to update.
397 \param texts an array of text values.
398 \param names parallel names to the array of text values.
399 \param n the dimension of texts[].
400 \note You do not need to call this function, it is called by INDI when new text values arrive from the client.
402 extern void ISNewText (const char *dev, const char *name, char *texts[],
403 char *names[], int n);
405 /** \brief Update the value of an existing number vector property.
406 \param dev the name of the device.
407 \param name the name of the number vector property to update.
408 \param doubles an array of number values.
409 \param names parallel names to the array of number values.
410 \param n the dimension of doubles[].
411 \note You do not need to call this function, it is called by INDI when new number values arrive from the client.
413 extern void ISNewNumber (const char *dev, const char *name, double *doubles,
414 char *names[], int n);
416 /** \brief Update the value of an existing switch vector property.
417 \param dev the name of the device.
418 \param name the name of the switch vector property to update.
419 \param states an array of switch states.
420 \param names parallel names to the array of switch states.
421 \param n the dimension of states[].
422 \note You do not need to call this function, it is called by INDI when new switch values arrive from the client.
424 extern void ISNewSwitch (const char *dev, const char *name, ISState *states,
425 char *names[], int n);
427 /** \brief Update data of an existing blob vector property.
428 \param dev the name of the device.
429 \param name the name of the blob vector property to update.
430 \param sizes an array of blob sizes in bytes.
431 \param blobs names of blob members to update. Each name and size pair form a blob member.
432 \param format Blob data format (e.g. fits.z).
433 \param n the number of blobs to update.
434 \note You do not need to call this function, it is called by INDI when new blob values arrive from the client.
437 extern void ISNewBLOB (const char *dev, const char *name, int sizes[],
438 char *blobs[], char *formats[], char *names[], int n);
440 /*@}*/
442 #ifdef __cplusplus
444 #endif
446 #endif