source: BAORadio/libindi/v1/indiapi.h @ 612

Last change on this file since 612 was 490, checked in by campagne, 14 years ago

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