source: BAORadio/libindi/v1.0.1/indiapi.h @ 693

Last change on this file since 693 was 501, checked in by frichard, 14 years ago

-BAOControl : petite interface permettant de contrôler les antennes via le pilote indi_BAO
-Le pilote indi_BAO utilise désormais libindi v 0.7
File size: 13.2 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="group__configFunctions.html">Configuration</a></li>
51<li><a href="classINDI_1_1BaseClient.html">Client API</a></li>
52</ul>
53
54
55\section Help
56
57You 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 */
77#define INDI_LIBV       0.7
78
79/*******************************************************************************
80 * Manifest constants
81 */
82
83/** \typedef ISState
84    \brief Switch state.
85*/
86typedef 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*/
95typedef 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*/
106typedef 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*/
116typedef 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*/
158typedef 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*/
176typedef 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*/
204typedef 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*/
232typedef 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*/
260typedef 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*/
271typedef 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*/
301typedef 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*/
312typedef 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 */
336typedef 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
359typedef 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
Note: See TracBrowser for help on using the repository browser.