Functions
FILE *	IUGetConfigFP (const char filename, const char dev, const char *mode, 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...

int	IUGetConfigNumber (const char dev, const char property, const char member, double value)
	IUGetConfigNumber Opens configuration file and reads number property. 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:

Last Saved Configuration: ~/.indi/driver_name_config.xml
Default Configuration: ~/.indi/driver_name_config.xml.default

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:

INDICONFIG environment variable: The functions checks if the envrionment variable is defined, and if so, it shall be used as the configuration filename
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

◆ IUGetConfigFP()

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

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

Parameters

filename	full 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.
dev	device name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the Detailed Description introduction.
mode	mode to open the file with (e.g. "w" or "r")
errmsg	In 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.

◆ IUGetConfigNumber()

int IUGetConfigNumber	(	const char *	dev,
		const char *	property,
		const char *	member,
		double *	value
	)

IUGetConfigNumber Opens configuration file and reads number property.

Parameters

dev	name of device
property	name of vector property
member	name of member property
value	pointer to save value of property if found.

Returns: 0 on success, -1 if not found.

◆ IUReadConfig()

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

filename	full 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.
dev	device name. This is used if the filename parameter is NULL, and INDICONFIG environment variable is not set as described in the Detailed Description introduction.
property	Property name to load configuration for. If NULL, all properties within the configuration file will be processed.
silent	If silent is 1, it will suppress any output messages to the driver.
errmsg	In 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.

◆ IUSaveConfigBLOB()

void IUSaveConfigBLOB	(	FILE *	fp,
		const IBLOBVectorProperty *	bvp
	)

Add a BLOB vector property value to the configuration file.

Parameters

fp	file pointer to a configuration file.
bvp	pointer 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.

◆ IUSaveConfigNumber()

void IUSaveConfigNumber	(	FILE *	fp,
		const INumberVectorProperty *	nvp
	)

Add a number vector property value to the configuration file.

Parameters

fp	file pointer to a configuration file.
nvp	pointer to a number vector property.

◆ IUSaveConfigSwitch()

void IUSaveConfigSwitch	(	FILE *	fp,
		const ISwitchVectorProperty *	svp
	)

Add a switch vector property value to the configuration file.

Parameters

fp	file pointer to a configuration file.
svp	pointer to a switch vector property.

◆ IUSaveConfigTag()

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

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

◆ IUSaveConfigText()

void IUSaveConfigText	(	FILE *	fp,
		const ITextVectorProperty *	tvp
	)

Add a text vector property value to the configuration file.

Parameters

fp	file pointer to a configuration file.
tvp	pointer to a text vector property.

◆ IUSaveDefaultConfig()

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_config	full 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_config	full 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.
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 Detailed Description introduction.

Functions

Detailed Description

Function Documentation

◆ IUGetConfigFP()

◆ IUGetConfigNumber()

◆ IUReadConfig()

◆ IUSaveConfigBLOB()

◆ IUSaveConfigNumber()

◆ IUSaveConfigSwitch()

◆ IUSaveConfigTag()

◆ IUSaveConfigText()

◆ IUSaveDefaultConfig()