[490] | 1 | #if 0 |
---|
| 2 | INDI |
---|
| 3 | Copyright (C) 2003 Elwood C. Downey |
---|
| 4 | |
---|
| 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. |
---|
| 9 | |
---|
| 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. |
---|
| 14 | |
---|
| 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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
---|
| 18 | |
---|
| 19 | #endif |
---|
| 20 | |
---|
| 21 | #ifndef INDI_API_H |
---|
| 22 | #define INDI_API_H |
---|
| 23 | |
---|
| 24 | /** \mainpage Instrument Neutral Distributed Interface INDI |
---|
| 25 | \section Introduction |
---|
| 26 | |
---|
| 27 | INDI is a simple XML-like communications protocol described for interactive and automated remote control of diverse instrumentation.\n |
---|
| 28 | |
---|
| 29 | INDI is small, easy to parse, and stateless. In the INDI paradigm each Device poses all command and status functions in terms of settings and getting Properties. Each Property is a vector of one or more names members. Each property has a current value vector; a target value vector; provides information about how it should be sequenced with respect to other Properties to accomplish one coordinated unit of observation; and provides hints as to how it might be displayed for interactive manipulation in a GUI.\n |
---|
| 30 | |
---|
| 31 | Clients learn the Properties of a particular Device at runtime using introspection. This decouples Client and Device implementation histories. Devices have a complete authority over whether to accept commands from Clients. INDI accommadates intermediate servers, broadcasting, and connection topologies ranging from one-to-one on a single system to many-to-many between systems of different genre.\n |
---|
| 32 | |
---|
| 33 | The INDI protocol can be nested within other XML elements such as constraints for automatic scheduling and execution.\n |
---|
| 34 | |
---|
| 35 | For a complete review on the INDI protocol, please refer to the INDI <a href="http://www.clearskyinstitute.com/INDI/INDI.pdf">white paper</a>. |
---|
| 36 | |
---|
| 37 | \section Audience Intended Audience |
---|
| 38 | |
---|
| 39 | INDI is intended for developers who seek a scalable API for device control and automation. Hardware drivers written under INDI can be used under any INDI-compatible client. INDI serves as a backend only, you need frontend clients to control devices. Current clients include <a href="http://edu.kde.org/kstars">KStars</a>, <a href="http://www.clearyskyinstitute.com/xephem">Xephem</a>, <a href="http://pygtkindiclient.sourceforge.net/">DCD</a>, and <a href="http://www.stargazing.net/astropc">Cartes du Ciel</a>. |
---|
| 40 | |
---|
| 41 | \section Development Developing under INDI |
---|
| 42 | |
---|
| 43 | <p>Please refere to the <a href="http://indi.sourceforge.net/index.php/Manual">INDI Developers Manual</a> for a complete guide on INDI's driver developemnt framework.</p> |
---|
| 44 | |
---|
| 45 | <p>The INDI Library API is divided into the following main sections:</p> |
---|
| 46 | <ul> |
---|
| 47 | <li><a href="indidevapi_8h.html">INDI Device API</a></li> |
---|
| 48 | <li><a href="indicom_8h.html">INDI Common Routine Library</a></li> |
---|
| 49 | <li><a href="lilxml_8h.html">INDI LilXML Library</a></li> |
---|
[501] | 50 | <li><a href="group__configFunctions.html">Configuration</a></li> |
---|
| 51 | <li><a href="classINDI_1_1BaseClient.html">Client API</a></li> |
---|
[490] | 52 | </ul> |
---|
| 53 | |
---|
| 54 | |
---|
| 55 | \section Help |
---|
| 56 | |
---|
| 57 | You can find information on INDI development in the <a href="http://indi.sf.net">INDI sourceforge</a> site. Furthermore, you can discuss INDI related issues on the <a href="http://sourceforge.net/mail/?group_id=90275">INDI development mailing list</a>. |
---|
| 58 | |
---|
| 59 | \author Elwood Downey |
---|
| 60 | \author Jasem Mutlaq |
---|
| 61 | */ |
---|
| 62 | |
---|
| 63 | /** \file indiapi.h |
---|
| 64 | \brief Constants and Data structure definitions for the interface to the reference INDI C API implementation. |
---|
| 65 | \author Elwood C. Downey |
---|
| 66 | */ |
---|
| 67 | |
---|
| 68 | /******************************************************************************* |
---|
| 69 | * INDI wire protocol version implemented by this API. |
---|
| 70 | * N.B. this is indepedent of the API itself. |
---|
| 71 | */ |
---|
| 72 | |
---|
| 73 | #define INDIV 1.7 |
---|
| 74 | |
---|
| 75 | |
---|
| 76 | /* INDI Library version */ |
---|
[504] | 77 | #define INDI_LIBV 0.8 |
---|
[490] | 78 | |
---|
| 79 | /******************************************************************************* |
---|
| 80 | * Manifest constants |
---|
| 81 | */ |
---|
| 82 | |
---|
| 83 | /** \typedef ISState |
---|
| 84 | \brief Switch state. |
---|
| 85 | */ |
---|
| 86 | typedef enum |
---|
| 87 | { |
---|
| 88 | ISS_OFF, /*!< Switch is OFF */ |
---|
| 89 | ISS_ON /*!< Switch is ON */ |
---|
| 90 | } ISState; /* switch state */ |
---|
| 91 | |
---|
| 92 | /** \typedef IPState |
---|
| 93 | \brief Property state. |
---|
| 94 | */ |
---|
| 95 | typedef enum |
---|
| 96 | { |
---|
| 97 | IPS_IDLE, /*!< State is idle */ |
---|
| 98 | IPS_OK, /*!< State is ok */ |
---|
| 99 | IPS_BUSY, /*!< State is busy */ |
---|
| 100 | IPS_ALERT /*!< State is alert */ |
---|
| 101 | } IPState; /* property state */ |
---|
| 102 | |
---|
| 103 | /** \typedef ISRule |
---|
| 104 | \brief Switch vector rule hint. |
---|
| 105 | */ |
---|
| 106 | typedef enum |
---|
| 107 | { |
---|
| 108 | ISR_1OFMANY, /*!< Only 1 switch of many can be ON (e.g. radio buttons) */ |
---|
| 109 | ISR_ATMOST1, /*!< There is only ONE switch */ |
---|
| 110 | ISR_NOFMANY /*!< Any number of switches can be ON (e.g. check boxes) */ |
---|
| 111 | } ISRule; /* switch vector rule hint */ |
---|
| 112 | |
---|
| 113 | /** \typedef IPerm |
---|
| 114 | \brief Permission hint, with respect to client. |
---|
| 115 | */ |
---|
| 116 | typedef enum |
---|
| 117 | { |
---|
| 118 | IP_RO, /*!< Read Only */ |
---|
| 119 | IP_WO, /*!< Write Only */ |
---|
| 120 | IP_RW /*!< Read & Write */ |
---|
| 121 | } IPerm; /* permission hint, WRT client */ |
---|
| 122 | |
---|
| 123 | /* The XML strings for these attributes may be any length but implementations |
---|
| 124 | * are only obligued to support these lengths for the various string attributes. |
---|
| 125 | */ |
---|
| 126 | #define MAXINDINAME 32 |
---|
| 127 | #define MAXINDILABEL 32 |
---|
| 128 | #define MAXINDIDEVICE 32 |
---|
| 129 | #define MAXINDIGROUP 32 |
---|
| 130 | #define MAXINDIFORMAT 32 |
---|
| 131 | #define MAXINDIBLOBFMT 32 |
---|
| 132 | #define MAXINDITSTAMP 32 |
---|
| 133 | |
---|
| 134 | /******************************************************************************* |
---|
| 135 | * Typedefs for each INDI Property type. |
---|
| 136 | * |
---|
| 137 | * INumber.format may be any printf-style appropriate for double |
---|
| 138 | * or style "m" to create sexigesimal using the form "%<w>.<f>m" where |
---|
| 139 | * <w> is the total field width. |
---|
| 140 | * <f> is the width of the fraction. valid values are: |
---|
| 141 | * 9 -> :mm:ss.ss |
---|
| 142 | * 8 -> :mm:ss.s |
---|
| 143 | * 6 -> :mm:ss |
---|
| 144 | * 5 -> :mm.m |
---|
| 145 | * 3 -> :mm |
---|
| 146 | * |
---|
| 147 | * examples: |
---|
| 148 | * |
---|
| 149 | * to produce use |
---|
| 150 | * |
---|
| 151 | * "-123:45" %7.3m |
---|
| 152 | * " 0:01:02" %9.6m |
---|
| 153 | */ |
---|
| 154 | |
---|
| 155 | /** \struct IText |
---|
| 156 | \brief One text descriptor. |
---|
| 157 | */ |
---|
| 158 | typedef struct { |
---|
| 159 | /** index name */ |
---|
| 160 | char name[MAXINDINAME]; |
---|
| 161 | /** short description */ |
---|
| 162 | char label[MAXINDILABEL]; |
---|
| 163 | /** malloced text string */ |
---|
| 164 | char *text; |
---|
| 165 | /** pointer to parent */ |
---|
| 166 | struct _ITextVectorProperty *tvp; |
---|
| 167 | /** handy place to hang helper info */ |
---|
| 168 | void *aux0; |
---|
| 169 | /** handy place to hang helper info */ |
---|
| 170 | void *aux1; |
---|
| 171 | } IText; |
---|
| 172 | |
---|
| 173 | /** \struct _ITextVectorProperty |
---|
| 174 | \brief Text vector property descriptor. |
---|
| 175 | */ |
---|
| 176 | typedef struct _ITextVectorProperty { |
---|
| 177 | /** device name */ |
---|
| 178 | char device[MAXINDIDEVICE]; |
---|
| 179 | /** property name */ |
---|
| 180 | char name[MAXINDINAME]; |
---|
| 181 | /** short description */ |
---|
| 182 | char label[MAXINDILABEL]; |
---|
| 183 | /** GUI grouping hint */ |
---|
| 184 | char group[MAXINDIGROUP]; |
---|
| 185 | /** client accessibility hint */ |
---|
| 186 | IPerm p; |
---|
| 187 | /** current max time to change, secs */ |
---|
| 188 | double timeout; |
---|
| 189 | /** current property state */ |
---|
| 190 | IPState s; |
---|
| 191 | /** texts comprising this vector */ |
---|
| 192 | IText *tp; |
---|
| 193 | /** dimension of tp[] */ |
---|
| 194 | int ntp; |
---|
| 195 | /** ISO 8601 timestamp of this event */ |
---|
| 196 | char timestamp[MAXINDITSTAMP]; |
---|
| 197 | /** handy place to hang helper info */ |
---|
| 198 | void *aux; |
---|
| 199 | } ITextVectorProperty; |
---|
| 200 | |
---|
| 201 | /** \struct INumber |
---|
| 202 | \brief One number descriptor. |
---|
| 203 | */ |
---|
| 204 | typedef struct { |
---|
| 205 | char name[MAXINDINAME]; /** index name */ |
---|
| 206 | char label[MAXINDILABEL]; /** short description */ |
---|
| 207 | char format[MAXINDIFORMAT]; /** GUI display format, see above */ |
---|
| 208 | double min, max; /** range, ignore if min == max */ |
---|
| 209 | double step; /** step size, ignore if step == 0 */ |
---|
| 210 | double value; /** current value */ |
---|
| 211 | struct _INumberVectorProperty *nvp; /** pointer to parent */ |
---|
| 212 | void *aux0, *aux1; /** handy place to hang helper info */ |
---|
| 213 | } INumber; |
---|
| 214 | |
---|
| 215 | /** \struct _INumberVectorProperty |
---|
| 216 | \brief Number vector property descriptor. |
---|
| 217 | |
---|
| 218 | INumber.format may be any printf-style appropriate for double or style "m" to create sexigesimal using the form "%\<w\>.\<f\>m" where:\n |
---|
| 219 | \<w\> is the total field width.\n |
---|
| 220 | \<f\> is the width of the fraction. valid values are:\n |
---|
| 221 | 9 -> \<w\>:mm:ss.ss \n |
---|
| 222 | 8 -> \<w\>:mm:ss.s \n |
---|
| 223 | 6 -> \<w\>:mm:ss \n |
---|
| 224 | 5 -> \<w\>:mm.m \n |
---|
| 225 | 3 -> \<w\>:mm \n |
---|
| 226 | |
---|
| 227 | examples:\n |
---|
| 228 | |
---|
| 229 | To produce "-123:45", use \%7.3m \n |
---|
| 230 | To produce " 0:01:02", use \%9.6m |
---|
| 231 | */ |
---|
| 232 | typedef struct _INumberVectorProperty { |
---|
| 233 | /** device name */ |
---|
| 234 | char device[MAXINDIDEVICE]; |
---|
| 235 | /** property name */ |
---|
| 236 | char name[MAXINDINAME]; |
---|
| 237 | /** short description */ |
---|
| 238 | char label[MAXINDILABEL]; |
---|
| 239 | /** GUI grouping hint */ |
---|
| 240 | char group[MAXINDIGROUP]; |
---|
| 241 | /** client accessibility hint */ |
---|
| 242 | IPerm p; |
---|
| 243 | /** current max time to change, secs */ |
---|
| 244 | double timeout; |
---|
| 245 | /** current property state */ |
---|
| 246 | IPState s; |
---|
| 247 | /** numbers comprising this vector */ |
---|
| 248 | INumber *np; |
---|
| 249 | /** dimension of np[] */ |
---|
| 250 | int nnp; |
---|
| 251 | /** ISO 8601 timestamp of this event */ |
---|
| 252 | char timestamp[MAXINDITSTAMP]; |
---|
| 253 | /** handy place to hang helper info */ |
---|
| 254 | void *aux; |
---|
| 255 | } INumberVectorProperty; |
---|
| 256 | |
---|
| 257 | /** \struct ISwitch |
---|
| 258 | \brief One switch descriptor. |
---|
| 259 | */ |
---|
| 260 | typedef struct { |
---|
| 261 | char name[MAXINDINAME]; /** index name */ |
---|
| 262 | char label[MAXINDILABEL]; /** this switch's label */ |
---|
| 263 | ISState s; /** this switch's state */ |
---|
| 264 | struct _ISwitchVectorProperty *svp; /** pointer to parent */ |
---|
| 265 | void *aux; /** handy place to hang helper info */ |
---|
| 266 | } ISwitch; |
---|
| 267 | |
---|
| 268 | /** \struct _ISwitchVectorProperty |
---|
| 269 | \brief Switch vector property descriptor. |
---|
| 270 | */ |
---|
| 271 | typedef struct _ISwitchVectorProperty { |
---|
| 272 | /** device name */ |
---|
| 273 | char device[MAXINDIDEVICE]; |
---|
| 274 | /** property name */ |
---|
| 275 | char name[MAXINDINAME]; |
---|
| 276 | /** short description */ |
---|
| 277 | char label[MAXINDILABEL]; |
---|
| 278 | /** GUI grouping hint */ |
---|
| 279 | char group[MAXINDIGROUP]; |
---|
| 280 | /** client accessibility hint */ |
---|
| 281 | IPerm p; |
---|
| 282 | /** switch behavior hint */ |
---|
| 283 | ISRule r; |
---|
| 284 | /** current max time to change, secs */ |
---|
| 285 | double timeout; |
---|
| 286 | /** current property state */ |
---|
| 287 | IPState s; |
---|
| 288 | /** switches comprising this vector */ |
---|
| 289 | ISwitch *sp; |
---|
| 290 | /** dimension of sp[] */ |
---|
| 291 | int nsp; |
---|
| 292 | /** ISO 8601 timestamp of this event */ |
---|
| 293 | char timestamp[MAXINDITSTAMP]; |
---|
| 294 | /** handy place to hang helper info */ |
---|
| 295 | void *aux; |
---|
| 296 | } ISwitchVectorProperty; |
---|
| 297 | |
---|
| 298 | /** \struct ILight |
---|
| 299 | \brief One light descriptor. |
---|
| 300 | */ |
---|
| 301 | typedef struct { |
---|
| 302 | char name[MAXINDINAME]; /** index name */ |
---|
| 303 | char label[MAXINDILABEL]; /** this lights's label */ |
---|
| 304 | IPState s; /** this lights's state */ |
---|
| 305 | struct _ILightVectorProperty *lvp; /** pointer to parent */ |
---|
| 306 | void *aux; /** handy place to hang helper info */ |
---|
| 307 | } ILight; |
---|
| 308 | |
---|
| 309 | /** \struct _ILightVectorProperty |
---|
| 310 | \brief Light vector property descriptor. |
---|
| 311 | */ |
---|
| 312 | typedef struct _ILightVectorProperty { |
---|
| 313 | /** device name */ |
---|
| 314 | char device[MAXINDIDEVICE]; |
---|
| 315 | /** property name */ |
---|
| 316 | char name[MAXINDINAME]; |
---|
| 317 | /** short description */ |
---|
| 318 | char label[MAXINDILABEL]; |
---|
| 319 | /** GUI grouping hint */ |
---|
| 320 | char group[MAXINDIGROUP]; |
---|
| 321 | /** current property state */ |
---|
| 322 | IPState s; |
---|
| 323 | /** lights comprising this vector */ |
---|
| 324 | ILight *lp; |
---|
| 325 | /** dimension of lp[] */ |
---|
| 326 | int nlp; |
---|
| 327 | /** ISO 8601 timestamp of this event */ |
---|
| 328 | char timestamp[MAXINDITSTAMP]; |
---|
| 329 | /** handy place to hang helper info */ |
---|
| 330 | void *aux; |
---|
| 331 | } ILightVectorProperty; |
---|
| 332 | |
---|
| 333 | /** \struct IBLOB |
---|
| 334 | \brief One Blob (Binary Large Object) descriptor. |
---|
| 335 | */ |
---|
| 336 | typedef struct { /* one BLOB descriptor */ |
---|
| 337 | /** index name */ |
---|
| 338 | char name[MAXINDINAME]; |
---|
| 339 | /** this BLOB's label */ |
---|
| 340 | char label[MAXINDILABEL]; |
---|
| 341 | /** format attr */ |
---|
| 342 | char format[MAXINDIBLOBFMT]; |
---|
| 343 | /** malloced binary large object bytes */ |
---|
| 344 | void *blob; |
---|
| 345 | /** bytes in blob */ |
---|
| 346 | int bloblen; |
---|
| 347 | /** n uncompressed bytes */ |
---|
| 348 | int size; |
---|
| 349 | /** pointer to parent */ |
---|
| 350 | struct _IBLOBVectorProperty *bvp; |
---|
| 351 | /** handy place to hang helper info */ |
---|
| 352 | void *aux0, *aux1, *aux2; |
---|
| 353 | } IBLOB; |
---|
| 354 | |
---|
| 355 | /** \struct _IBLOBVectorProperty |
---|
| 356 | \brief BLOB (Binary Large Object) vector property descriptor. |
---|
| 357 | */ |
---|
| 358 | |
---|
| 359 | typedef struct _IBLOBVectorProperty { /* BLOB vector property descriptor */ |
---|
| 360 | /** device name */ |
---|
| 361 | char device[MAXINDIDEVICE]; |
---|
| 362 | /** property name */ |
---|
| 363 | char name[MAXINDINAME]; |
---|
| 364 | /** short description */ |
---|
| 365 | char label[MAXINDILABEL]; |
---|
| 366 | /** GUI grouping hint */ |
---|
| 367 | char group[MAXINDIGROUP]; |
---|
| 368 | /** client accessibility hint */ |
---|
| 369 | IPerm p; |
---|
| 370 | /** current max time to change, secs */ |
---|
| 371 | double timeout; |
---|
| 372 | /** current property state */ |
---|
| 373 | IPState s; |
---|
| 374 | /** BLOBs comprising this vector */ |
---|
| 375 | IBLOB *bp; |
---|
| 376 | /** dimension of bp[] */ |
---|
| 377 | int nbp; |
---|
| 378 | /** ISO 8601 timestamp of this event */ |
---|
| 379 | char timestamp[MAXINDITSTAMP]; |
---|
| 380 | /** handy place to hang helper info */ |
---|
| 381 | void *aux; |
---|
| 382 | } IBLOBVectorProperty; |
---|
| 383 | |
---|
| 384 | |
---|
| 385 | /** \brief Handy macro to find the number of elements in array a[]. Must be used with actual array, not pointer. |
---|
| 386 | */ |
---|
| 387 | #define NARRAY(a) (sizeof(a)/sizeof(a[0])) |
---|
| 388 | |
---|
| 389 | #endif |
---|