Instrument Neutral Distributed Interface INDI  1.4.1
Functions
Configuration Functions: Functions drivers call to save and load configuraion options.

Functions

FILE * IUGetConfigFP (const char *filename, const char *dev, char errmsg[])
 Open a configuration file for writing and return a configuration file FILE pointer. More...
 
int IUReadConfig (const char *filename, const char *dev, const char *property, int silent, char errmsg[])
 Loads and processes a configuration file. More...
 
void IUSaveDefaultConfig (const char *source_config, const char *dest_config, const char *dev)
 Copies an existing configuration file into a default configuration file. More...
 
void IUSaveConfigTag (FILE *fp, int ctag, const char *dev, int silent)
 Add opening or closing tag to a configuration file. More...
 
void IUSaveConfigNumber (FILE *fp, const INumberVectorProperty *nvp)
 Add a number vector property value to the configuration file. More...
 
void IUSaveConfigText (FILE *fp, const ITextVectorProperty *tvp)
 Add a text vector property value to the configuration file. More...
 
void IUSaveConfigSwitch (FILE *fp, const ISwitchVectorProperty *svp)
 Add a switch vector property value to the configuration file. More...
 
void IUSaveConfigBLOB (FILE *fp, const IBLOBVectorProperty *bvp)
 Add a BLOB vector property value to the configuration file. More...
 

Detailed Description

Drivers can save properties states and values in an XML configuration file. The following functions take an optional filename parameter which specifies the full path of the configuration file. If the filename is set to NULL, the configuration file is locally stored in ~/.indi. By default, two configuration files may exist for each driver:

libindi stores the configuration parameters enclosed in newXXX commands. Therefore, if a configuration file is loaded, the driver property gets updated as if a client is setting these values. This is important to note since some configuration options may only available when the device is powered up or is in a particular state.

If no filename is supplied, each function will try to create the configuration files in the following order:

  1. INDICONFIG environment variable: The functions checks if the envrionment variable is defined, and if so, it shall be used as the configuration filename
  2. Generate filename: If the device_name is supplied, the function will attempt to set the configuration filename to ~/.indi/device_name_config.xml
Author
Jasem Mutlaq
Note
Drivers subclassing INDI::DefaultDevice do not need to call the configuration functions directly as it is handled internally by the class.
Version
libindi 1.1+

Function Documentation

FILE* IUGetConfigFP ( const char *  filename,
const char *  dev,
char  errmsg[] 
)

Open a configuration file for writing and return a configuration file FILE pointer.

Parameters
filenamefull path of the configuration file. If set, the function will attempt to open it for writing. If set to NULL, it will attempt to generate the filename as described in the Detailed Description introduction and then open it for writing.
devdevice name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the Detailed Description introduction.
errmsgIn case of errors, store the error message in this buffer. The size of the buffer must be at least MAXRBUF.
Returns
pointer to FILE if configuration file is opened successful, otherwise NULL and errmsg is set.

Definition at line 1343 of file indidriver.c.

int IUReadConfig ( const char *  filename,
const char *  dev,
const char *  property,
int  silent,
char  errmsg[] 
)

Loads and processes a configuration file.

Once a configuration file is successful loaded, the function will iterate over the enclosed newXXX commands, and dispatches each command to the driver. Subsequently, the driver receives the updated property value in the driver's ISNewXXX functions. The driver may call this function at any time. However, it is usually called either on driver startup or on device power up. By default, all the properties are read from the configuration file. To load a specific property, pass the property name, otherwise pass NULL to retrive all properties.

Parameters
filenamefull path of the configuration file. If set, the function will attempt to load the file. If set to NULL, it will attempt to generate the filename as described in the Detailed Description introduction and then load it.
devdevice name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the Detailed Description introduction.
propertyProperty name to load configuration for. If NULL, all properties within the configuration file will be processed.
silentIf silent is 1, it will suppress any output messages to the driver.
errmsgIn case of errors, store the error message in this buffer. The size of the buffer must be at least MAXRBUF.
Returns
0 on successful, -1 if there is an error and errmsg is set.

Definition at line 1199 of file indidriver.c.

void IUSaveConfigBLOB ( FILE *  fp,
const IBLOBVectorProperty bvp 
)

Add a BLOB vector property value to the configuration file.

Parameters
fpfile pointer to a configuration file.
bvppointer to a BLOB vector property.
Note
If the BLOB size is large, this function will block until the BLOB contents are written to the file.

Definition at line 1458 of file indidriver.c.

void IUSaveConfigNumber ( FILE *  fp,
const INumberVectorProperty nvp 
)

Add a number vector property value to the configuration file.

Parameters
fpfile pointer to a configuration file.
nvppointer to a number vector property.

Definition at line 1403 of file indidriver.c.

void IUSaveConfigSwitch ( FILE *  fp,
const ISwitchVectorProperty svp 
)

Add a switch vector property value to the configuration file.

Parameters
fpfile pointer to a configuration file.
svppointer to a switch vector property.

Definition at line 1440 of file indidriver.c.

void IUSaveConfigTag ( FILE *  fp,
int  ctag,
const char *  dev,
int  silent 
)

Add opening or closing tag to a configuration file.

A configuration file root XML element is <INDIDriver>. This functions add <INDIDriver> or </INDIDriver> as required.

Parameters
fpfile pointer to a configuration file.
ctagIf 0, <INDIDriver> is appened to the configuration file, otherwise </INDIDriver> is appeneded and the fp is closed.
devdevice name. Used only for sending notification to the driver if silent is set to 1.
silentIf silent is 1, it will suppress any output messages to the driver.

Definition at line 1382 of file indidriver.c.

void IUSaveConfigText ( FILE *  fp,
const ITextVectorProperty tvp 
)

Add a text vector property value to the configuration file.

Parameters
fpfile pointer to a configuration file.
tvppointer to a text vector property.

Definition at line 1422 of file indidriver.c.

void IUSaveDefaultConfig ( const char *  source_config,
const char *  dest_config,
const char *  dev 
)

Copies an existing configuration file into a default configuration file.

If no default configuration file for the supplied dev exists, it gets created and its contentes copied from an exiting source configuration file. Usually, when the user saves the configuration file of a driver for the first time, IUSaveDefaultConfig is called to create the default configuration file. If the default configuration file already exists, the function performs no action and returns.

Parameters
source_configfull path of the source configuration file to read. If set, the function will attempt to load the file. If set to NULL, it will attempt to generate the filename as described in the Detailed Description introduction and then load it.
dest_configfull path of the destination default configuration file to write. If set, the function will attempt to load the file. If set to NULL, it will attempt to generate the filename as described in the Detailed Description introduction and then load it. 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.
devdevice 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 Detailed Description introduction.

Definition at line 1270 of file indidriver.c.