1 | #if 0 |
---|
2 | INDI |
---|
3 | Copyright (C) 2003-2006 Elwood C. Downey |
---|
4 | |
---|
5 | Updated by Jasem Mutlaq (2003-2010) |
---|
6 | |
---|
7 | This library is free software; you can redistribute it and/or |
---|
8 | modify it under the terms of the GNU Lesser General Public |
---|
9 | License as published by the Free Software Foundation; either |
---|
10 | version 2.1 of the License, or (at your option) any later version. |
---|
11 | |
---|
12 | This library is distributed in the hope that it will be useful, |
---|
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
---|
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
---|
15 | Lesser General Public License for more details. |
---|
16 | |
---|
17 | You should have received a copy of the GNU Lesser General Public |
---|
18 | License along with this library; if not, write to the Free Software |
---|
19 | Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA |
---|
20 | |
---|
21 | #endif |
---|
22 | |
---|
23 | #ifndef INDIDRIVER_H |
---|
24 | #define INDIDRIVER_H |
---|
25 | |
---|
26 | #ifdef __cplusplus |
---|
27 | extern "C" { |
---|
28 | #endif |
---|
29 | |
---|
30 | /* insure RO properties are never modified. RO Sanity Check */ |
---|
31 | typedef struct |
---|
32 | { |
---|
33 | char propName[MAXINDINAME]; |
---|
34 | IPerm perm; |
---|
35 | } ROSC; |
---|
36 | |
---|
37 | extern ROSC *roCheck; |
---|
38 | extern int nroCheck; /* # of elements in roCheck */ |
---|
39 | extern int verbose; /* chatty */ |
---|
40 | extern char *me; /* a.out name */ |
---|
41 | extern LilXML *clixml; /* XML parser context */ |
---|
42 | |
---|
43 | extern int dispatch (XMLEle *root, char msg[]); |
---|
44 | extern void clientMsgCB(int fd, void *arg); |
---|
45 | |
---|
46 | /** |
---|
47 | * \defgroup configFunctions Configuration Functions: Functions drivers call to save and load configuraion options. |
---|
48 | |
---|
49 | <p>Drivers can save properties states and values in an XML configuration file. The following functions take an optinal filename |
---|
50 | parameter which specifies the full path of the configuration file. If the filename is set to NULL, the configuration file |
---|
51 | is locally stored in ~/.indi. By default, two configuration files may exist for each driver:</p> |
---|
52 | <ul> |
---|
53 | <li>Last Saved Configuration: ~/.indi/driver_name_config.xml</li> |
---|
54 | <li>Default Configuration: ~/.indi/driver_name_config.xml.default</li> |
---|
55 | </ul> |
---|
56 | |
---|
57 | <p>libindi stores the configuration parameters enclosed in newXXX commands. Therefore, if a configuration file is loaded, |
---|
58 | the driver property gets updated as if a client is setting these values. This is important to note since some configuration |
---|
59 | options may only available when the device is powered up or is in a particular state.</p> |
---|
60 | |
---|
61 | <p>If no filename is supplied, each function will try to create the configuration files in the following order:</p> |
---|
62 | <ol> |
---|
63 | <li>INDICONFIG environment variable: The functions checks if the envrionment variable is defined, and if so, it shall |
---|
64 | be used as the configuration filename</li> |
---|
65 | <li>Generate filename: If the <i>device_name</i> is supplied, the function will attempt to set the configuration filename to ~/.indi/device_name_config.xml</li> |
---|
66 | </ol> |
---|
67 | \note Drivers subclassing INDI::DefaultDevice do not need to call the configuration functions directly as it is handled internally by the class. |
---|
68 | \version libindi 0.7+ |
---|
69 | */ |
---|
70 | |
---|
71 | |
---|
72 | /*@{*/ |
---|
73 | |
---|
74 | /** \brief Open a configuration file for writing and return a configuration file FILE pointer. |
---|
75 | \param filename full path of the configuration file. If set, the function will attempt to open it for writing. |
---|
76 | If set to NULL, it will attempt to generate the filename as described in the <b>Detailed Description</b> introduction and then open it for writing. |
---|
77 | \param dev device name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the <b>Detailed Description</b> introduction. |
---|
78 | \param errmsg In case of errors, store the error message in this buffer. The size of the buffer must be at least MAXRBUF. |
---|
79 | \return pointer to FILE if configuration file is opened successful, otherwise NULL and errmsg is set. |
---|
80 | */ |
---|
81 | extern FILE * IUGetConfigFP(const char *filename, const char *dev, char errmsg[]); |
---|
82 | |
---|
83 | /** \brief Loads and processes a configuration file. |
---|
84 | |
---|
85 | Once a configuration file is successful loaded, the function will iterate over the enclosed newXXX commands, and dispatches |
---|
86 | each command to the driver. Subsequently, the driver receives the updated property value in the driver's ISNewXXX functions. |
---|
87 | The driver may call this function at any time. However, it is usually called either on driver startup or on device power up. |
---|
88 | |
---|
89 | \param filename full path of the configuration file. If set, the function will attempt to load the file. |
---|
90 | If set to NULL, it will attempt to generate the filename as described in the <b>Detailed Description</b> introduction and then load it. |
---|
91 | \param dev device name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the <b>Detailed Description</b> introduction. |
---|
92 | \param errmsg In case of errors, store the error message in this buffer. The size of the buffer must be at least MAXRBUF. |
---|
93 | \return 0 on successful, -1 if there is an error and errmsg is set. |
---|
94 | */ |
---|
95 | extern int IUReadConfig(const char *filename, const char *dev, char errmsg[]); |
---|
96 | |
---|
97 | /** \brief Copies an existing configuration file into a default configuration file. |
---|
98 | |
---|
99 | If no <i>default</i> configuration file for the supplied <i>dev</i> exists, it gets created and its contentes copied from an exiting source configuration file. |
---|
100 | Usually, when the user saves the configuration file of a driver for the first time, IUSaveDefaultConfig is called to create the default |
---|
101 | configuration file. If the default configuration file already exists, the function performs no action and returns. |
---|
102 | \param source_config full path of the source configuration file to read. If set, the function will attempt to load the file. |
---|
103 | If set to NULL, it will attempt to generate the filename as described in the <b>Detailed Description</b> introduction and then load it. |
---|
104 | \param dest_config full path of the destination default configuration file to write. If set, the function will attempt to load the file. |
---|
105 | If set to NULL, it will attempt to generate the filename as described in the <b>Detailed Description</b> introduction and then load it. |
---|
106 | If the file already exists, the function returns. If the file doesn't exist, it gets created and its contents copied from the source_config file. |
---|
107 | \param dev device name. This is used if either the source_config or desg_config are NULL, and INDICONFIG environment variable is not set as described in the <b>Detailed Description</b> introduction. |
---|
108 | */ |
---|
109 | extern void IUSaveDefaultConfig(const char *source_config, const char *dest_config, const char *dev); |
---|
110 | |
---|
111 | /** \brief Add opening or closing tag to a configuration file. |
---|
112 | |
---|
113 | A configuration file root XML element is @<INDIDriver>@. This functions add @<INDIDriver>@ or @</INDIDriver>@ as required. |
---|
114 | \param fp file pointer to a configuration file. |
---|
115 | \param ctag If 0, @<INDIDriver>@ is appened to the configuration file, otherwise @</INDIDriver>@ is appeneded and the <i>fp</i> is closed. |
---|
116 | */ |
---|
117 | extern void IUSaveConfigTag(FILE *fp, int ctag); |
---|
118 | |
---|
119 | /** \brief Add a number vector property value to the configuration file |
---|
120 | \param fp file pointer to a configuration file. |
---|
121 | \param nvp pointer to a number vector property. |
---|
122 | */ |
---|
123 | extern void IUSaveConfigNumber (FILE *fp, const INumberVectorProperty *nvp); |
---|
124 | |
---|
125 | /** \brief Add a text vector property value to the configuration file |
---|
126 | \param fp file pointer to a configuration file. |
---|
127 | \param tvp pointer to a text vector property. |
---|
128 | */ |
---|
129 | extern void IUSaveConfigText (FILE *fp, const ITextVectorProperty *tvp); |
---|
130 | |
---|
131 | /** \brief Add a switch vector property value to the configuration file |
---|
132 | \param fp file pointer to a configuration file. |
---|
133 | \param svp pointer to a switch vector property. |
---|
134 | */ |
---|
135 | extern void IUSaveConfigSwitch (FILE *fp, const ISwitchVectorProperty *svp); |
---|
136 | |
---|
137 | /** \brief Add a BLOB vector property value to the configuration file |
---|
138 | \param fp file pointer to a configuration file. |
---|
139 | \param bvp pointer to a BLOB vector property. |
---|
140 | \note If the BLOB size is large, this function will block until the BLOB contents are written to the file. |
---|
141 | */ |
---|
142 | extern void IUSaveConfigBLOB (FILE *fp, const IBLOBVectorProperty *bvp); |
---|
143 | |
---|
144 | /*@}*/ |
---|
145 | |
---|
146 | #ifdef __cplusplus |
---|
147 | } |
---|
148 | #endif |
---|
149 | |
---|
150 | #endif |
---|