[501] | 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 |
---|