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; 8 you can redistribute it and / or 9 modify it under the terms of the GNU Lesser General Public 10 License as published by the Free Software Foundation; 11 either 12 version 2.1 of the License, or (at your option) any later version. 13 14 This library is distributed in the hope that it will be useful, 15 but WITHOUT ANY WARRANTY; 16 without even the implied warranty of 17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 18 Lesser General Public License for more details. 19 20 You should have received a copy of the GNU Lesser General Public 21 License along with this library; 22 if not, write to the Free Software 23 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110 - 1301 USA 24 25 #endif 26 27 #pragma once 28 29 /** \file indidevapi.h 30 \brief Interface to the reference INDI C API device implementation on the Device Driver side. 31 * 32 \author Elwood C. Downey 33 \author Jasem Mutlaq 34 35 This file is divided into two main sections:\n 36 <ol><li> Functions the INDI device driver framework defines which the Driver may 37 call:</li> 38 39 <ul><li>IDxxx functions to send messages to an INDI client. Please note that it is recommended to use the 40 INDI Library wrapper functions instead of calling IDxxx directly. 41 <ul> 42 <li>IDMessage: Use @ref INDI::Logger "INDI Logging Framework" functions (e.g. LOG_DEBUG..etc) instead.</li> 43 <li>IDDefXXX: use @ref INDI::DefaultDevice "INDI Default Device" defXXX functions intead.</li> 44 </ul> 45 </li> 46 <li>IExxx functions to implement the event driven model.</li> 47 <li>IUxxx functions to perform handy utility functions.</li></ul> 48 49 <li>Functions the INDI device driver framework calls which the Driver must 50 define:</li> 51 52 <ul><li>ISxxx to respond to messages from a Client.</li></ul></ol> 53 54 <p>These functions are the interface to the INDI C-language Device Driver 55 reference implementation library. Any driver that uses this interface is 56 expected to \#include "indidevapi.h" and to link with indidrivermain.o and 57 eventloop.o. Indidevapi.h further includes indiapi.h. The former contains 58 the prototypes for the functions documented here, although many functions 59 take arguments defined in the latter.</p> 60 61 <p>These functions make it much easier to write a compliant INDI driver than 62 starting from scratch, and also serve as a concrete 63 example of the interactions an INDI driver, in any language, is expected to 64 accommodate.</p> 65 66 <p>The reference driver framework and the optimizations made within the reference 67 indiserver both assume and require that one driver program implements exactly 68 one logical INDI device.</p> 69 70 <p>The functions in this framework fall into two broad categories. Some are 71 functions that a driver must define because they are called by the reference 72 framework; these functions begin with IS. The remaining functions are library 73 utilities a driver may use to do important operations.</p> 74 75 <p>A major point to realize is that an INDI driver built with this framework 76 does not contain the C main() function. As soon as a driver begins executing, 77 it listens on stdin for INDI messages. Only when a valid and appropriate 78 message is received will it then call the driver via one of the IS functions. 79 The driver is then expected to respond promptly by calling one of the ID 80 library functions. It may also use any of the IU utility functions as desired 81 to make processing a message easier.</p> 82 83 <p>Rather separate from these IS, ID and IU functions are a collection of 84 functions that utilize the notion of a callback. In a callback design, 85 the driver registers a function with the framework to be called under 86 certain circumstances. When said circumstances occur, the framework will 87 call the callback function. The driver never calls these callbacks directly. 88 These callback functions begin with IE. They can arrange for a callback 89 function to be called under three kinds of circumstances: when a given file 90 descriptor may be read without blocking (because either data is available 91 or EOF has been encountered), when a given time interval has elapsed, or 92 when the framework has nothing urgent to do. The callback functions for each 93 circumstance must be written according to a well defined prototype since, 94 after all, the framework must know how to call the callback correctlty.</p> 95 96 */ 97 98 /******************************************************************************* 99 * get the data structures 100 */ 101 102 #include "indiapi.h" 103 #include "lilxml.h" 104 105 /******************************************************************************* 106 ******************************************************************************* 107 * 108 * Functions the INDI device driver framework defines which the Driver may call 109 * 110 ******************************************************************************* 111 ******************************************************************************* 112 */ 113 114 #ifdef __cplusplus 115 extern "C" { 116 #endif 117 118 /** 119 * \defgroup d2cFunctions IDDef Functions: Functions drivers call to define their properties to clients. 120 121 <p>Each of the following functions creates the appropriate XML formatted 122 INDI message from its arguments and writes it to stdout. From there, is it 123 typically read by indiserver which then sends it to the clients that have 124 expressed interest in messages from the Device indicated in the message.</p> 125 126 <p>In addition to type-specific arguments, all end with a printf-style format 127 string, and appropriate subsequent arguments, that form the \param msg 128 attribute within the INDI message. If the format argument is NULL, no message 129 attribute is included with the message. Note that a \e timestamp 130 attribute is also always added automatically based on the clock on the 131 computer on which this driver is running.</p> 132 133 */ 134 135 // enable warnings for printf-style functions 136 #ifndef ATTRIBUTE_FORMAT_PRINTF 137 # ifdef __GNUC__ 138 # define ATTRIBUTE_FORMAT_PRINTF(A, B) __attribute__((format(printf, (A), (B)))) 139 # else 140 # define ATTRIBUTE_FORMAT_PRINTF(A, B) 141 # endif 142 #endif 143 144 /*@{*/ 145 146 /** \brief Tell client to create a text vector property. 147 \param t pointer to the vector text property to be defined. 148 \param msg message in printf style to send to the client. May be NULL. 149 */ 150 extern void IDDefText(const ITextVectorProperty *t, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 151 extern void IDDefTextVA(const ITextVectorProperty *t, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 152 153 /** \brief Tell client to create a number number property. 154 \param n pointer to the vector number property to be defined. 155 \param msg message in printf style to send to the client. May be NULL. 156 */ 157 extern void IDDefNumber(const INumberVectorProperty *n, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 158 extern void IDDefNumberVA(const INumberVectorProperty *n, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 159 160 /** \brief Tell client to create a switch vector property. 161 \param s pointer to the vector switch property to be defined. 162 \param msg message in printf style to send to the client. May be NULL. 163 */ 164 extern void IDDefSwitch(const ISwitchVectorProperty *s, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 165 extern void IDDefSwitchVA(const ISwitchVectorProperty *s, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 166 167 /** \brief Tell client to create a light vector property. 168 \param l pointer to the vector light property to be defined. 169 \param msg message in printf style to send to the client. May be NULL. 170 */ 171 extern void IDDefLight(const ILightVectorProperty *l, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 172 extern void IDDefLightVA(const ILightVectorProperty *l, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 173 174 /** \brief Tell client to create a BLOB vector property. 175 \param b pointer to the vector BLOB property to be defined. 176 \param msg message in printf style to send to the client. May be NULL. 177 */ 178 extern void IDDefBLOB(const IBLOBVectorProperty *b, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 179 extern void IDDefBLOBVA(const IBLOBVectorProperty *b, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 180 181 /*@}*/ 182 183 /** 184 * \defgroup d2cuFunctions IDSet Functions: Functions drivers call to tell clients of new values for existing properties. 185 */ 186 /*@{*/ 187 188 /** \brief Tell client to update an existing text vector property. 189 \param t pointer to the vector text property. 190 \param msg message in printf style to send to the client. May be NULL. 191 */ 192 extern void IDSetText(const ITextVectorProperty *t, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 193 extern void IDSetTextVA(const ITextVectorProperty *t, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 194 195 /** \brief Tell client to update an existing number vector property. 196 \param n pointer to the vector number property. 197 \param msg message in printf style to send to the client. May be NULL. 198 */ 199 extern void IDSetNumber(const INumberVectorProperty *n, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 200 extern void IDSetNumberVA(const INumberVectorProperty *n, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 201 202 /** \brief Tell client to update an existing switch vector property. 203 \param s pointer to the vector switch property. 204 \param msg message in printf style to send to the client. May be NULL. 205 */ 206 extern void IDSetSwitch(const ISwitchVectorProperty *s, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 207 extern void IDSetSwitchVA(const ISwitchVectorProperty *s, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 208 209 /** \brief Tell client to update an existing light vector property. 210 \param l pointer to the vector light property. 211 \param msg message in printf style to send to the client. May be NULL. 212 */ 213 extern void IDSetLight(const ILightVectorProperty *l, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 214 extern void IDSetLightVA(const ILightVectorProperty *l, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 215 216 /** \brief Tell client to update an existing BLOB vector property. 217 \param b pointer to the vector BLOB property. 218 \param msg message in printf style to send to the client. May be NULL. 219 */ 220 extern void IDSetBLOB(const IBLOBVectorProperty *b, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 221 extern void IDSetBLOBVA(const IBLOBVectorProperty *b, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 222 223 /*@}*/ 224 225 /** 226 * \defgroup d2duFunctions ID Functions: Functions to delete properties, and log messages locally or remotely. 227 */ 228 /*@{*/ 229 230 /** \brief Function Drivers call to send log messages to Clients. 231 232 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. 233 234 \param dev device name 235 \param msg message in printf style to send to the client. 236 */ 237 extern void IDMessage(const char *dev, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(2, 3); 238 extern void IDMessageVA(const char *dev, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(2, 0); 239 240 /** \brief Function Drivers call to inform Clients a Property is no longer available, or the entire device is gone if name is NULL. 241 242 \param dev device name. If device name is NULL, the entire device will be deleted. 243 \param name property name to be deleted. 244 \param msg message in printf style to send to the client. 245 */ 246 extern void IDDelete(const char *dev, const char *name, const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(3, 4); 247 extern void IDDeleteVA(const char *dev, const char *name, const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(3, 0); 248 249 /** \brief Function Drivers call to log a message locally. 250 251 The message is not sent to any Clients. 252 253 \param msg message in printf style to send to the client. 254 */ 255 extern void IDLog(const char *msg, ...) ATTRIBUTE_FORMAT_PRINTF(1, 2); 256 extern void IDLogVA(const char *msg, va_list arg) ATTRIBUTE_FORMAT_PRINTF(1, 0); 257 258 /*@}*/ 259 260 /** 261 * \defgroup snoopFunctions ISnoop Functions: Functions drivers call to snoop on other drivers. 262 263 */ 264 /*@{*/ 265 266 /** \typedef BLOBHandling 267 \brief How drivers handle BLOBs incoming from snooping drivers */ 268 typedef enum 269 { 270 B_NEVER = 0, /*!< Never receive BLOBs */ 271 B_ALSO, /*!< Receive BLOBs along with normal messages */ 272 B_ONLY /*!< ONLY receive BLOBs from drivers, ignore all other traffic */ 273 } BLOBHandling; 274 275 /** \brief Function a Driver calls to snoop on another Device. Snooped messages will then arrive via ISSnoopDevice. 276 \param snooped_device name of the device to snoop. 277 \param snooped_property name of the snooped property in the device. 278 */ 279 extern void IDSnoopDevice(const char *snooped_device, const char *snooped_property); 280 281 /** \brief Function a Driver calls to control whether they will receive BLOBs from snooped devices. 282 \param snooped_device name of the device to snoop. 283 \param snooped_property name of property to snoop. If NULL, then all BLOBs from the given device are snooped. 284 \param bh How drivers handle BLOBs incoming from snooping drivers. 285 */ 286 extern void IDSnoopBLOBs(const char *snooped_device, const char *snooped_property, BLOBHandling bh); 287 288 /*@}*/ 289 290 /** 291 * \defgroup deventFunctions IE Functions: Functions drivers call to register with the INDI event utilities. 292 293 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. 294 */ 295 /*@{*/ 296 297 /* signature of a callback, timout caller and work procedure function */ 298 299 /** \typedef IE_CBF 300 \brief Signature of a callback. */ 301 typedef void(IE_CBF)(int readfiledes, void *userpointer); 302 303 /** \typedef IE_TCF 304 \brief Signature of a timeout caller. */ 305 typedef void(IE_TCF)(void *userpointer); 306 307 /** \typedef IE_WPF 308 \brief Signature of a work procedure function. */ 309 typedef void(IE_WPF)(void *userpointer); 310 311 /* functions to add and remove callbacks, timers and work procedures */ 312 313 /** \brief Register a new callback, \e fp, to be called with \e userpointer as argument when \e readfiledes is ready. 314 * 315 * \param readfiledes file descriptor. 316 * \param fp a pointer to the callback function. 317 * \param userpointer a pointer to be passed to the callback function when called. 318 * \return a unique callback id for use with IERmCallback(). 319 */ 320 extern int IEAddCallback(int readfiledes, IE_CBF *fp, void *userpointer); 321 322 /** \brief Remove a callback function. 323 * 324 * \param callbackid the callback ID returned from IEAddCallback() 325 */ 326 extern void IERmCallback(int callbackid); 327 328 /** \brief Register a new single-shot timer function, \e fp, to be called with \e ud as argument after \e ms. 329 * 330 * \param millisecs timer period in milliseconds. 331 * \param fp a pointer to the callback function. 332 * \param userpointer a pointer to be passed to the callback function when called. 333 * \return a unique id for use with IERmTimer(). 334 */ 335 extern int IEAddTimer(int millisecs, IE_TCF *fp, void *userpointer); 336 337 /** \brief Register a new periodic timer function, \e fp, to be called with \e ud as argument after \e ms. 338 * 339 * \param millisecs timer period in milliseconds. 340 * \param fp a pointer to the callback function. 341 * \param userpointer a pointer to be passed to the callback function when called. 342 * \return a unique id for use with IERmTimer(). 343 */ 344 extern int IEAddPeriodicTimer(int millisecs, IE_TCF *fp, void *userpointer); 345 346 /** \brief Returns the timer's remaining value in milliseconds left until the timeout. 347 * 348 * \param timerid the timer callback ID returned from IEAddTimer() or IEAddPeriodicTimer() 349 * \return If the timer not exists, the returned value will be -1. 350 */ 351 extern int IERemainingTimer(int timerid); 352 353 /** Returns the timer's remaining value in nanoseconds left until the timeout. 354 * 355 * \param tid the timer callback ID returned from addTimer() or addPeriodicTimer() 356 * \return If the timer not exists, the returned value will be -1. 357 */ 358 extern int IENSecRemainingTimer(int tid); 359 360 /** \brief Remove the timer with the given \e timerid, as returned from IEAddTimer() or IEAddPeriodicTimer(). 361 * 362 * \param timerid the timer callback ID returned from IEAddTimer() or IEAddPeriodicTimer(). 363 */ 364 extern void IERmTimer(int timerid); 365 366 /** \brief Add a new work procedure, fp, to be called with ud when nothing else to do. 367 * 368 * \param fp a pointer to the work procedure callback function. 369 * \param userpointer a pointer to be passed to the callback function when called. 370 * \return a unique id for use with IERmWorkProc(). 371 */ 372 extern int IEAddWorkProc(IE_WPF *fp, void *userpointer); 373 374 /** \brief Remove a work procedure. 375 * 376 * \param workprocid The unique ID for the work procedure to be removed. 377 */ 378 extern void IERmWorkProc(int workprocid); 379 380 /* wait in-line for a flag to set, presumably by another event function */ 381 382 extern int IEDeferLoop(int maxms, int *flagp); 383 extern int IEDeferLoop0(int maxms, int *flagp); 384 385 /*@}*/ 386 387 /** 388 * \defgroup dutilFunctions IU Functions: Functions drivers call to perform handy utility routines. 389 390 <p>This section describes handy utility functions that are provided by the 391 framework for tasks commonly required in the processing of client 392 messages. It is not strictly necessary to use these functions, but it 393 both prudent and efficient to do so.</P> 394 395 <p>These do not communicate with the Client in any way.</p> 396 */ 397 /*@{*/ 398 399 /** \brief Find an IText member in a vector text property. 400 * 401 * \param tvp a pointer to a text vector property. 402 * \param name the name of the member to search for. 403 * \return a pointer to an IText member on match, or NULL if nothing is found. 404 */ 405 extern IText *IUFindText(const ITextVectorProperty *tvp, const char *name); 406 407 /** \brief Find an INumber member in a number text property. 408 * 409 * \param nvp a pointer to a number vector property. 410 * \param name the name of the member to search for. 411 * \return a pointer to an INumber member on match, or NULL if nothing is found. 412 */ 413 extern INumber *IUFindNumber(const INumberVectorProperty *nvp, const char *name); 414 415 /** \brief Find an ISwitch member in a vector switch property. 416 * 417 * \param svp a pointer to a switch vector property. 418 * \param name the name of the member to search for. 419 * \return a pointer to an ISwitch member on match, or NULL if nothing is found. 420 */ 421 extern ISwitch *IUFindSwitch(const ISwitchVectorProperty *svp, const char *name); 422 423 /** \brief Find an ILight member in a vector Light property. 424 * 425 * \param lvp a pointer to a Light vector property. 426 * \param name the name of the member to search for. 427 * \return a pointer to an ILight member on match, or NULL if nothing is found. 428 */ 429 extern ILight *IUFindLight(const ILightVectorProperty *lvp, const char *name); 430 431 /** \brief Find an IBLOB member in a vector BLOB property. 432 * 433 * \param bvp a pointer to a BLOB vector property. 434 * \param name the name of the member to search for. 435 * \return a pointer to an IBLOB member on match, or NULL if nothing is found. 436 */ 437 extern IBLOB *IUFindBLOB(const IBLOBVectorProperty *bvp, const char *name); 438 439 /** \brief Returns the first ON switch it finds in the vector switch property. 440 441 * \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. 442 * 443 * \param sp a pointer to a switch vector property. 444 * \return a pointer to the \e first ON ISwitch member if found. If all switches are off, NULL is returned. 445 */ 446 extern ISwitch *IUFindOnSwitch(const ISwitchVectorProperty *sp); 447 448 /** \brief Returns the index of the string in a string array 449 * 450 * \param needle the string to match against each element in the hay 451 * \param hay a pointer to a string array to search in 452 * \param n the size of hay 453 * \return index of needle if found in the hay. Otherwise -1 if not found. 454 */ 455 extern int IUFindIndex(const char *needle, char **hay, unsigned int n); 456 457 /** \brief Returns the index of first ON switch it finds in the vector switch property. 458 459 * \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. 460 * 461 * \param sp a pointer to a switch vector property. 462 * \return index to the \e first ON ISwitch member if found. If all switches are off, -1 is returned. 463 */ 464 465 extern int IUFindOnSwitchIndex(const ISwitchVectorProperty *sp); 466 467 /** \brief Returns the name of the first ON switch it finds in the supplied arguments. 468 469 * \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. 470 * \note This is a convience function intended to be used in ISNewSwitch(...) function to find out ON switch name without having to change actual switch state via IUUpdateSwitch(..) 471 * 472 * \param states list of switch states passed by ISNewSwitch() 473 * \param names list of switch names passed by ISNewSwitch() 474 * \param n number of switches passed by ISNewSwitch() 475 * \return name of the \e first ON ISwitch member if found. If all switches are off, NULL is returned. 476 */ 477 extern const char *IUFindOnSwitchName(ISState *states, char *names[], int n); 478 479 /** \brief Reset all switches in a switch vector property to OFF. 480 * 481 * \param svp a pointer to a switch vector property. 482 */ 483 extern void IUResetSwitch(ISwitchVectorProperty *svp); 484 485 /** \brief Update all switches in a switch vector property. 486 * 487 * \param svp a pointer to a switch vector property. 488 * \param states the states of the new ISwitch members. 489 * \param names the names of the ISwtich members to update. 490 * \param n the number of ISwitch members to update. 491 * \return 0 if update successful, -1 otherwise. 492 */ 493 extern int IUUpdateSwitch(ISwitchVectorProperty *svp, ISState *states, char *names[], int n); 494 495 /** \brief Update all numbers in a number vector property. 496 * 497 * \param nvp a pointer to a number vector property. 498 * \param values the states of the new INumber members. 499 * \param names the names of the INumber members to update. 500 * \param n the number of INumber members to update. 501 * \return 0 if update successful, -1 otherwise. Update will fail if values are out of scope, or in case of property name mismatch. 502 */ 503 extern int IUUpdateNumber(INumberVectorProperty *nvp, double values[], char *names[], int n); 504 505 /** \brief Update all text members in a text vector property. 506 * 507 * \param tvp a pointer to a text vector property. 508 * \param texts a pointer to the text members 509 * \param names the names of the IText members to update. 510 * \param n the number of IText members to update. 511 * \return 0 if update successful, -1 otherwise. Update will fail in case of property name mismatch. 512 */ 513 extern int IUUpdateText(ITextVectorProperty *tvp, char *texts[], char *names[], int n); 514 515 /** \brief Update all BLOB members in a BLOB vector property. 516 * 517 * \param bvp a pointer to a BLOB vector property. 518 * \param sizes sizes of the blobs. 519 * \param blobsizes size of the blobs, raw without compression. 520 * \param blobs a pointer to the BLOB members 521 * \param names the names of the IBLOB members to update. 522 * \param formats The blob format or extension. 523 * \param n the number of IBLOB members to update. 524 * \return 0 if update successful, -1 otherwise. Update will fail in case of property name mismatch. 525 */ 526 extern int IUUpdateBLOB(IBLOBVectorProperty *bvp, int sizes[], int blobsizes[], char *blobs[], char *formats[], 527 char *names[], int n); 528 529 /** \brief Function to save blob metadata in the corresponding blob. 530 \param bp pointer to an IBLOB member. 531 \param size size of the blob buffer encoded in base64 532 \param blobsize actual size of the buffer after base64 decoding. This is the actual byte count used in drivers. 533 \param blob pointer to the blob buffer 534 \param format format of the blob buffer 535 \note Do not call this function directly, it is called internally by IUUpdateBLOB. 536 */ 537 extern int IUSaveBLOB(IBLOB *bp, int size, int blobsize, char *blob, char *format); 538 539 /** \brief Function to update the min and max elements of a number in the client 540 \param nvp pointer to an INumberVectorProperty. 541 \warning This call is not INDI protocol compliant. It sends setNumberVector along with updated Min/Max/Step values so that the client 542 updates the range accordingly for this property. In the INDI-compliant paradigm, it is NOT possible to update min/max/step step of an existing number 543 property and the only way is to do so is to delete and redefine the number property again. However, due to the many problems with approach in device drivers, 544 INDI Library defines this function to simplify the update process without requiring a complete delete/define cycle. 545 */ 546 extern void IUUpdateMinMax(const INumberVectorProperty *nvp); 547 548 /** \brief Function to reliably save new text in a IText. 549 \param tp pointer to an IText member. 550 \param newtext the new text to be saved 551 */ 552 extern void IUSaveText(IText *tp, const char *newtext); 553 554 /** \brief Assign attributes for a switch property. The switch's auxiliary elements will be set to NULL. 555 \param sp pointer a switch property to fill 556 \param name the switch name 557 \param label the switch label 558 \param s the switch state (ISS_ON or ISS_OFF) 559 */ 560 extern void IUFillSwitch(ISwitch *sp, const char *name, const char *label, ISState s); 561 562 /** \brief Assign attributes for a light property. The light's auxiliary elements will be set to NULL. 563 \param lp pointer a light property to fill 564 \param name the light name 565 \param label the light label 566 \param s the light state (IDLE, WARNING, OK, ALERT) 567 */ 568 extern void IUFillLight(ILight *lp, const char *name, const char *label, IPState s); 569 570 /** \brief Assign attributes for a number property. The number's auxiliary elements will be set to NULL. 571 \param np pointer a number property to fill 572 \param name the number name 573 \param label the number label 574 \param format the number format in printf style (e.g. "%02d") 575 \param min the minimum possible value 576 \param max the maximum possible value 577 \param step the step used to climb from minimum value to maximum value 578 \param value the number's current value 579 */ 580 extern void IUFillNumber(INumber *np, const char *name, const char *label, const char *format, double min, double max, 581 double step, double value); 582 583 /** \brief Assign attributes for a text property. The text's auxiliary elements will be set to NULL. 584 \param tp pointer a text property to fill 585 \param name the text name 586 \param label the text label 587 \param initialText the initial text 588 */ 589 extern void IUFillText(IText *tp, const char *name, const char *label, const char *initialText); 590 591 /** \brief Assign attributes for a BLOB property. The BLOB's data and auxiliary elements will be set to NULL. 592 \param bp pointer a BLOB property to fill 593 \param name the BLOB name 594 \param label the BLOB label 595 \param format the BLOB format. 596 */ 597 extern void IUFillBLOB(IBLOB *bp, const char *name, const char *label, const char *format); 598 599 /** \brief Assign attributes for a switch vector property. The vector's auxiliary elements will be set to NULL. 600 \param svp pointer a switch vector property to fill 601 \param sp pointer to an array of switches 602 \param nsp the dimension of sp 603 \param dev the device name this vector property belongs to 604 \param name the vector property name 605 \param label the vector property label 606 \param group the vector property group 607 \param p the vector property permission 608 \param r the switches behavior 609 \param timeout vector property timeout in seconds 610 \param s the vector property initial state. 611 */ 612 extern void IUFillSwitchVector(ISwitchVectorProperty *svp, ISwitch *sp, int nsp, const char *dev, const char *name, 613 const char *label, const char *group, IPerm p, ISRule r, double timeout, IPState s); 614 615 /** \brief Assign attributes for a light vector property. The vector's auxiliary elements will be set to NULL. 616 \param lvp pointer a light vector property to fill 617 \param lp pointer to an array of lights 618 \param nlp the dimension of lp 619 \param dev the device name this vector property belongs to 620 \param name the vector property name 621 \param label the vector property label 622 \param group the vector property group 623 \param s the vector property initial state. 624 */ 625 extern void IUFillLightVector(ILightVectorProperty *lvp, ILight *lp, int nlp, const char *dev, const char *name, 626 const char *label, const char *group, IPState s); 627 628 /** \brief Assign attributes for a number vector property. The vector's auxiliary elements will be set to NULL. 629 \param nvp pointer a number vector property to fill 630 \param np pointer to an array of numbers 631 \param nnp the dimension of np 632 \param dev the device name this vector property belongs to 633 \param name the vector property name 634 \param label the vector property label 635 \param group the vector property group 636 \param p the vector property permission 637 \param timeout vector property timeout in seconds 638 \param s the vector property initial state. 639 */ 640 extern void IUFillNumberVector(INumberVectorProperty *nvp, INumber *np, int nnp, const char *dev, const char *name, 641 const char *label, const char *group, IPerm p, double timeout, IPState s); 642 643 /** \brief Assign attributes for a text vector property. The vector's auxiliary elements will be set to NULL. 644 \param tvp pointer a text vector property to fill 645 \param tp pointer to an array of texts 646 \param ntp the dimension of tp 647 \param dev the device name this vector property belongs to 648 \param name the vector property name 649 \param label the vector property label 650 \param group the vector property group 651 \param p the vector property permission 652 \param timeout vector property timeout in seconds 653 \param s the vector property initial state. 654 */ 655 extern void IUFillTextVector(ITextVectorProperty *tvp, IText *tp, int ntp, const char *dev, const char *name, 656 const char *label, const char *group, IPerm p, double timeout, IPState s); 657 658 /** \brief Assign attributes for a BLOB vector property. The vector's auxiliary elements will be set to NULL. 659 \param bvp pointer a BLOB vector property to fill 660 \param bp pointer to an array of BLOBs 661 \param nbp the dimension of bp 662 \param dev the device name this vector property belongs to 663 \param name the vector property name 664 \param label the vector property label 665 \param group the vector property group 666 \param p the vector property permission 667 \param timeout vector property timeout in seconds 668 \param s the vector property initial state. 669 */ 670 extern void IUFillBLOBVector(IBLOBVectorProperty *bvp, IBLOB *bp, int nbp, const char *dev, const char *name, 671 const char *label, const char *group, IPerm p, double timeout, IPState s); 672 673 /** \brief Update a snooped number vector property from the given XML root element. 674 \param root XML root elememnt containing the snopped property content 675 \param nvp a pointer to the number vector property to be updated. 676 \return 0 if cracking the XML element and updating the property proceeded without errors, -1 if trouble. 677 */ 678 extern int IUSnoopNumber(XMLEle *root, INumberVectorProperty *nvp); 679 680 /** \brief Update a snooped text vector property from the given XML root element. 681 \param root XML root elememnt containing the snopped property content 682 \param tvp a pointer to the text vector property to be updated. 683 \return 0 if cracking the XML element and updating the property proceeded without errors, -1 if trouble. 684 */ 685 extern int IUSnoopText(XMLEle *root, ITextVectorProperty *tvp); 686 687 /** \brief Update a snooped light vector property from the given XML root element. 688 \param root XML root elememnt containing the snopped property content 689 \param lvp a pointer to the light vector property to be updated. 690 \return 0 if cracking the XML element and updating the property proceeded without errors, -1 if trouble. 691 */ 692 extern int IUSnoopLight(XMLEle *root, ILightVectorProperty *lvp); 693 694 /** \brief Update a snooped switch vector property from the given XML root element. 695 \param root XML root elememnt containing the snopped property content 696 \param svp a pointer to the switch vector property to be updated. 697 \return 0 if cracking the XML element and updating the property proceeded without errors, -1 if trouble. 698 */ 699 extern int IUSnoopSwitch(XMLEle *root, ISwitchVectorProperty *svp); 700 701 /** \brief Update a snooped BLOB vector property from the given XML root element. 702 \param root XML root elememnt containing the snopped property content 703 \param bvp a pointer to the BLOB vector property to be updated. 704 \return 0 if cracking the XML element and updating the property proceeded without errors, -1 if trouble. 705 */ 706 extern int IUSnoopBLOB(XMLEle *root, IBLOBVectorProperty *bvp); 707 708 /*@}*/ 709 710 /******************************************************************************* 711 ******************************************************************************* 712 * 713 * Functions the INDI Device Driver framework calls which the Driver must 714 * define. 715 * 716 ******************************************************************************* 717 ******************************************************************************* 718 */ 719 720 /** 721 * \defgroup dcuFunctions IS Functions: Functions all drivers must define. 722 723 This section defines functions that must be defined in each driver. These 724 functions are never called by the driver, but are called by the driver 725 framework. These must always be defined even if they do nothing. 726 */ 727 /*@{*/ 728 729 /** \brief Get Device Properties 730 \param dev the name of the device. 731 732 This function is called by the framework whenever the driver has received a 733 getProperties message from an INDI client. The argument \param dev is either a 734 string containing the name of the device specified within the message, or NULL 735 if no device was specified. If the driver does not recognize the device, it 736 should ignore the message and do nothing. If dev matches the device the driver 737 is implementing, or dev is NULL, the driver must respond by sending one defXXX 738 message to describe each property defined by this device, including its 739 current (or initial) value. The recommended way to send these messages is to 740 call the appropriate IDDef functions. 741 */ 742 extern void ISGetProperties(const char *dev); 743 744 /** \brief Update the value of an existing text vector property. 745 \param dev the name of the device. 746 \param name the name of the text vector property to update. 747 \param texts an array of text values. 748 \param names parallel names to the array of text values. 749 \param n the dimension of texts[]. 750 \note You do not need to call this function, it is called by INDI when new text values arrive from the client. 751 */ 752 extern void ISNewText(const char *dev, const char *name, char *texts[], char *names[], int n); 753 754 /** \brief Update the value of an existing number vector property. 755 \param dev the name of the device. 756 \param name the name of the number vector property to update. 757 \param values an array of number values. 758 \param names parallel names to the array of number values. 759 \param n the dimension of doubles[]. 760 \note You do not need to call this function, it is called by INDI when new number values arrive from the client. 761 */ 762 extern void ISNewNumber(const char *dev, const char *name, double *values, char *names[], int n); 763 764 /** \brief Update the value of an existing switch vector property. 765 \param dev the name of the device. 766 \param name the name of the switch vector property to update. 767 \param states an array of switch states. 768 \param names parallel names to the array of switch states. 769 \param n the dimension of states[]. 770 \note You do not need to call this function, it is called by INDI when new switch values arrive from the client. 771 */ 772 extern void ISNewSwitch(const char *dev, const char *name, ISState *states, char *names[], int n); 773 774 /** \brief Update data of an existing blob vector property. 775 \param dev the name of the device. 776 \param name the name of the blob vector property to update. 777 \param sizes an array of base64 blob sizes in bytes \e before decoding. 778 \param blobsizes an array of the sizes of blobs \e after decoding from base64. 779 \param blobs an array of decoded data. Each blob size is found in \e blobsizes array. 780 \param formats Blob data format (e.g. fits.z). 781 \param names names of blob members to update. 782 \param n the number of blobs to update. 783 \note You do not need to call this function, it is called by INDI when new blob values arrive from the client. 784 e.g. BLOB element with name names[0] has data located in blobs[0] with size sizes[0] and format formats[0]. 785 */ 786 787 extern void ISNewBLOB(const char *dev, const char *name, int sizes[], int blobsizes[], char *blobs[], char *formats[], 788 char *names[], int n); 789 790 /** \brief Function defined by Drivers that is called when another Driver it is snooping (by having previously called IDSnoopDevice()) sent any INDI message. 791 \param root The argument contains the full message exactly as it was sent by the driver. 792 \e Hint: use the IUSnoopXXX utility functions to help crack the message if it was one of setXXX or defXXX. 793 */ 794 extern void ISSnoopDevice(XMLEle *root); 795 796 /*@}*/ 797 798 /* Handy readability macro to avoid unused variables warnings */ 799 #define INDI_UNUSED(x) (void)x 800 801 /** \brief Extract dev and name attributes from an XML element. 802 \param root The XML element to be parsed. 803 \param dev pointer to an allocated buffer to save the extracted element device name attribute. 804 The buffer size must be at least MAXINDIDEVICE bytes. 805 \param name pointer to an allocated buffer to save the extracted elemented name attribute. 806 The buffer size must be at least MAXINDINAME bytes. 807 \param msg pointer to an allocated char buffer to store error messages. The minimum buffer size is MAXRBUF. 808 \return 0 if successful, -1 if error is encountered and msg is set. 809 */ 810 extern int crackDN(XMLEle *root, char **dev, char **name, char msg[]); 811 812 /** \brief Extract property state (Idle, OK, Busy, Alert) from the supplied string. 813 \param str A string representation of the state. 814 \param ip Pointer to IPState structure to store the extracted property state. 815 \return 0 if successful, -1 if error is encountered. 816 */ 817 extern int crackIPState(const char *str, IPState *ip); 818 819 /** \brief Extract switch state (On or Off) from the supplied string. 820 \param str A string representation of the switch state. 821 \param ip Pointer to ISState structure to store the extracted switch state. 822 \return 0 if successful, -1 if error is encountered. 823 */ 824 extern int crackISState(const char *str, ISState *ip); 825 826 /** \brief Extract property permission state (RW, RO, WO) from the supplied string. 827 \param str A string representation of the permission state. 828 \param ip Pointer to IPerm structure to store the extracted permission state. 829 \return 0 if successful, -1 if error is encountered. 830 */ 831 extern int crackIPerm(const char *str, IPerm *ip); 832 833 /** \brief Extract switch rule (OneOfMany, OnlyOne..etc) from the supplied string. 834 \param str A string representation of the switch rule. 835 \param ip Pointer to ISRule structure to store the extracted switch rule. 836 \return 0 if successful, -1 if error is encountered. 837 */ 838 extern int crackISRule(const char *str, ISRule *ip); 839 840 /** \return Returns a string representation of the supplied property state. */ 841 extern const char *pstateStr(IPState s); 842 /** \return Returns a string representation of the supplied switch status. */ 843 extern const char *sstateStr(ISState s); 844 /** \return Returns a string representation of the supplied switch rule. */ 845 extern const char *ruleStr(ISRule r); 846 /** \return Returns a string representation of the supplied permission value. */ 847 extern const char *permStr(IPerm p); 848 849 extern void xmlv1(); 850 851 #ifdef __cplusplus 852 } 853 #endif 854