kstars/kstars/indi/indiapi.h

   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  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 accommpdates 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">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>, and <a href="http://www.stargazing.net/astropc">Cartes du Ciel</a>.
  40
  41 \section Development Developing under INDI
  42
  43 Please refere to the <a href="http://indi.sf.net">INDI Developers Manual</a> for a complete guide on INDI's driver developemnt framework.
  44
  45 \section Help
  46
  47 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>.
  48
  49 \author Elwood Downey
  50 \author Jasem Mutlaq
  51 */
  52
  53 /** \file indiapi.h
  54     \brief Constants and Data structure definitions for the interface to the reference INDI C API implementation.
  55     \author Elwood C. Downey
  56 */
  57
  58 /*******************************************************************************
  59  * INDI wire protocol version implemented by this API.
  60  * N.B. this is indepedent of the API itself.
  61  */
  62
  63 #define INDIV   1.5
  64
  65 /*******************************************************************************
  66  * Manifest constants
  67  */
  68
  69 /** \typedef ISState
  70     \brief Switch state.
  71 */
  72 typedef enum {
  73     ISS_OFF, ISS_ON
  74 } ISState;                              /* switch state */
  75
  76 /** \typedef IPState
  77     \brief Property state.
  78 */
  79 typedef enum {
  80     IPS_IDLE, IPS_OK, IPS_BUSY, IPS_ALERT
  81 } IPState;                              /* property state */
  82
  83 /** \typedef ISRule
  84     \brief Switch vector rule hint.
  85 */
  86 typedef enum {
  87     ISR_1OFMANY, ISR_ATMOST1, ISR_NOFMANY
  88 } ISRule;                               /* switch vector rule hint */
  89
  90 /** \typedef IPerm
  91     \brief Permission hint, with respect to client.
  92 */
  93 typedef enum {
  94     IP_RO, IP_WO, IP_RW
  95 } IPerm;                                /* permission hint, WRT client */
  96
  97 /* The XML strings for these attributes may be any length but implementations
  98  * are only obligued to support these lengths for the various string attributes.
  99  */
 100 #define MAXINDINAME     32
 101 #define MAXINDILABEL    32
 102 #define MAXINDIDEVICE   32
 103 #define MAXINDIGROUP    32
 104 #define MAXINDIFORMAT   32
 105 #define MAXINDIBLOBFMT  32
 106 #define MAXINDITSTAMP   32
 107
 108 /*******************************************************************************
 109  * Typedefs for each INDI Property type.
 110  *
 111  * INumber.format may be any printf-style appropriate for double
 112  * or style "m" to create sexigesimal using the form "%<w>.<f>m" where
 113  *   <w> is the total field width.
 114  *   <f> is the width of the fraction. valid values are:
 115  *      9  ->  :mm:ss.ss
 116  *      8  ->  :mm:ss.s
 117  *      6  ->  :mm:ss
 118  *      5  ->  :mm.m
 119  *      3  ->  :mm
 120  *
 121  * examples:
 122  *
 123  *   to produce     use
 124  *
 125  *    "-123:45"    %7.3m
 126  *  "  0:01:02"    %9.6m
 127  */
 128
 129 /** \struct IText
 130     \brief One text descriptor.
 131 */
 132 typedef struct {
 133     /** index name */
 134     char name[MAXINDINAME];
 135     /** short description */
 136     char label[MAXINDILABEL];
 137     /** malloced text string */
 138     char *text;
 139     /** pointer to parent */
 140     struct _ITextVectorProperty *tvp;
 141     /** handy place to hang helper info */
 142     void *aux0;
 143     /** handy place to hang helper info */
 144     void *aux1;
 145 } IText;
 146
 147 /** \struct _ITextVectorProperty
 148     \brief Text vector property descriptor.
 149 */
 150 typedef struct _ITextVectorProperty {
 151     /** device name */
 152     char device[MAXINDIDEVICE];
 153     /** property name */
 154     char name[MAXINDINAME];
 155     /** short description */
 156     char label[MAXINDILABEL];
 157     /** GUI grouping hint */
 158     char group[MAXINDIGROUP];
 159     /** client accessibility hint */
 160     IPerm p;
 161     /** current max time to change, secs */
 162     double timeout;
 163     /** current property state */
 164     IPState s;
 165     /** texts comprising this vector */
 166     IText *tp;
 167     /** dimension of tp[] */
 168     int ntp;
 169     /** ISO 8601 timestamp of this event */
 170     char timestamp[MAXINDITSTAMP];
 171     /** handy place to hang helper info */
 172     void *aux;
 173 } ITextVectorProperty;
 174
 175 /** \struct INumber
 176     \brief One number descriptor.
 177 */
 178 typedef struct {
 179     char name[MAXINDINAME];             /** index name */
 180     char label[MAXINDILABEL];           /** short description */
 181     char format[MAXINDIFORMAT];         /** GUI display format, see above */
 182     double min, max;                    /** range, ignore if min == max */
 183     double step;                        /** step size, ignore if step == 0 */
 184     double value;                       /** current value */
 185     struct _INumberVectorProperty *nvp; /** pointer to parent */
 186     void *aux0, *aux1;                  /** handy place to hang helper info */
 187 } INumber;
 188
 189 /** \struct _INumberVectorProperty
 190     \brief Number vector property descriptor.
 191
 192     INumber.format may be any printf-style appropriate for double or style "m" to create sexigesimal using the form "%\<w\>.\<f\>m" where:\n
 193     \<w\> is the total field width.\n
 194     \<f\> is the width of the fraction. valid values are:\n
 195         9  ->  \<w\>:mm:ss.ss \n
 196         8  ->  \<w\>:mm:ss.s \n
 197         6  ->  \<w\>:mm:ss \n
 198         5  ->  \<w\>:mm.m \n
 199         3  ->  \<w\>:mm \n
 200
 201    examples:\n
 202
 203    To produce "-123:45", use \%7.3m \n
 204    To produce "  0:01:02", use \%9.6m
 205 */
 206 typedef struct _INumberVectorProperty {
 207     /** device name */
 208     char device[MAXINDIDEVICE];
 209     /** property name */
 210     char name[MAXINDINAME];
 211     /** short description */
 212     char label[MAXINDILABEL];
 213     /** GUI grouping hint */
 214     char group[MAXINDIGROUP];
 215     /** client accessibility hint */
 216     IPerm p;
 217     /** current max time to change, secs */
 218     double timeout;
 219     /** current property state */
 220     IPState s;
 221     /** numbers comprising this vector */
 222     INumber *np;
 223     /** dimension of np[] */
 224     int nnp;
 225     /** ISO 8601 timestamp of this event */
 226     char timestamp[MAXINDITSTAMP];
 227     /** handy place to hang helper info */
 228     void *aux;
 229 } INumberVectorProperty;
 230
 231 /** \struct ISwitch
 232     \brief One switch descriptor.
 233 */
 234 typedef struct {
 235     char name[MAXINDINAME];             /** index name */
 236     char label[MAXINDILABEL];           /** this switch's label */
 237     ISState s;                          /** this switch's state */
 238     struct _ISwitchVectorProperty *svp; /** pointer to parent */
 239     void *aux;                          /** handy place to hang helper info */
 240 } ISwitch;
 241
 242 /** \struct _ISwitchVectorProperty
 243     \brief Switch vector property descriptor.
 244 */
 245 typedef struct _ISwitchVectorProperty {
 246     /** device name */
 247     char device[MAXINDIDEVICE];
 248     /** property name */
 249     char name[MAXINDINAME];
 250     /** short description */
 251     char label[MAXINDILABEL];
 252     /** GUI grouping hint */
 253     char group[MAXINDIGROUP];
 254     /** client accessibility hint */
 255     IPerm p;
 256     /** switch behavior hint */
 257     ISRule r;
 258     /** current max time to change, secs */
 259     double timeout;
 260     /** current property state */
 261     IPState s;
 262     /** switches comprising this vector */
 263     ISwitch *sp;
 264     /** dimension of sp[] */
 265     int nsp;
 266     /** ISO 8601 timestamp of this event */
 267     char timestamp[MAXINDITSTAMP];
 268     /** handy place to hang helper info */
 269     void *aux;
 270 } ISwitchVectorProperty;
 271
 272 /** \struct ILight
 273     \brief One light descriptor.
 274 */
 275 typedef struct {
 276     char name[MAXINDINAME];             /** index name */
 277     char label[MAXINDILABEL];           /** this lights's label */
 278     IPState s;                          /** this lights's state */
 279     struct _ILightVectorProperty *lvp;  /** pointer to parent */
 280     void *aux;                          /** handy place to hang helper info */
 281 } ILight;
 282
 283 /** \struct _ILightVectorProperty
 284     \brief Light vector property descriptor.
 285 */
 286 typedef struct _ILightVectorProperty {
 287     /** device name */
 288     char device[MAXINDIDEVICE];
 289     /** property name */
 290     char name[MAXINDINAME];
 291     /** short description */
 292     char label[MAXINDILABEL];
 293     /** GUI grouping hint */
 294     char group[MAXINDIGROUP];
 295     /** current property state */
 296     IPState s;
 297     /** lights comprising this vector */
 298     ILight *lp;
 299     /** dimension of lp[] */
 300     int nlp;
 301     /** ISO 8601 timestamp of this event */
 302     char timestamp[MAXINDITSTAMP];
 303     /** handy place to hang helper info */
 304     void *aux;
 305 } ILightVectorProperty;
 306
 307 /** \struct IBLOB
 308     \brief One Blob (Binary Large Object) descriptor.
 309  */
 310 typedef struct {                        /* one BLOB descriptor */
 311   /** index name */
 312   char name[MAXINDINAME];
 313   /** this BLOB's label */
 314   char label[MAXINDILABEL];
 315   /** format attr */
 316   char format[MAXINDIBLOBFMT];
 317   /** malloced binary large object bytes */
 318   void *blob;
 319   /** bytes in blob */
 320   int bloblen;
 321   /** n uncompressed bytes */
 322   int size;
 323   /** pointer to parent */
 324   struct _IBLOBVectorProperty *bvp;
 325   /** handy place to hang helper info */
 326   void *aux0, *aux1, *aux2;
 327 } IBLOB;
 328
 329 /** \struct _IBLOBVectorProperty
 330     \brief BLOB (Binary Large Object) vector property descriptor.
 331  */
 332
 333 typedef struct _IBLOBVectorProperty {   /* BLOB vector property descriptor */
 334   /** device name */
 335   char device[MAXINDIDEVICE];
 336   /** property name */
 337   char name[MAXINDINAME];
 338   /** short description */
 339   char label[MAXINDILABEL];
 340   /** GUI grouping hint */
 341   char group[MAXINDIGROUP];
 342   /** client accessibility hint */
 343   IPerm p;
 344   /** current max time to change, secs */
 345   double timeout;
 346   /** current property state */
 347   IPState s;
 348   /** BLOBs comprising this vector */
 349   IBLOB *bp;
 350   /** dimension of bp[] */
 351   int nbp;
 352   /** ISO 8601 timestamp of this event */
 353   char timestamp[MAXINDITSTAMP];
 354   /** handy place to hang helper info */
 355   void *aux;
 356 } IBLOBVectorProperty;
 357
 358
 359 /** \brief Handy macro to find the number of elements in array a[]. Must be used with actual array, not pointer.
 360 */
 361 #define NARRAY(a)       (sizeof(a)/sizeof(a[0]))
 362
 363 #endif