Detailed Description

xPL provides a powerful yet simple mechanism for device configuration, intended to suit the requirements of devices ranging from embedded micro-controllers through to powerful PC applications.
When a device is started for the first time, it should begin sending out config.basic or config.app messages at intervals of 1 minute. These messages contain the same information as their hbeat.basic and hbeat.app counterparts, and are used to alert an xPL Configuration Manager that the device is waiting to be configured. If a device has previously been configured, and was able to retain that configuration information locally, it should not go into configuration mode, but should instead go directly to sending out regular heartbeat messages, indicating that it is ready for operation.

Collaboration diagram for Configurable devices:

Data Structures
struct	_gxPLDeviceConfigItem
	Describe a element of configuration. More...

Functions
gxPLDevice *	gxPLAppAddConfigurableDevice (gxPLApplication app, const char vendor_id, const char device_id, const char filename)
	Adds a new configurable device. More...

const char *	gxPLDeviceConfigFilenameGet (const gxPLDevice *device)
	Return the installed config file, if any. More...

int	gxPLDeviceConfigItemAdd (gxPLDevice device, const char name, gxPLConfigurableType type, int max_values)
	Add a new configurable. More...

int	gxPLDeviceConfigItemClearAll (gxPLDevice *device)
	Clear all configurable values out. More...

gxPLDeviceConfigItem *	gxPLDeviceConfigItemFind (const gxPLDevice device, const char name)
	Search for a configurable. More...

int	gxPLDeviceConfigItemRemove (gxPLDevice device, const char name)
	Remove a configurable. More...

int	gxPLDeviceConfigItemRemoveAll (gxPLDevice *device)
	Remove all configurables. More...

int	gxPLDeviceConfigListenerAdd (gxPLDevice device, gxPLDeviceConfigListener listener, void udata)
	Add a device config changed listener. More...

int	gxPLDeviceConfigListenerRemove (gxPLDevice *device, gxPLDeviceConfigListener listener)
	Remove a config changed listener. More...

int	gxPLDeviceConfigSave (const gxPLDevice *device)
	Save out the current configuration. More...

int	gxPLDeviceConfigValueAdd (gxPLDevice device, const char name, const char *value)
	Add a device item value. More...

int	gxPLDeviceConfigValueClearAll (gxPLDevice device, const char name)
	Clear values for a given configurable. More...

int	gxPLDeviceConfigValueCount (const gxPLDevice device, const char name)
	Return the number of values for a given configurable. More...

const char *	gxPLDeviceConfigValueGet (gxPLDevice device, const char name)
	Return the value of the first/only index for an item. More...

const char *	gxPLDeviceConfigValueGetAt (gxPLDevice device, const char name, int index)
	Return the value at the given index. More...

int	gxPLDeviceConfigValueSet (gxPLDevice device, const char name, const char *value)
	Simple form to set first/only value in an item. More...

int	gxPLDeviceConfigValueSetAt (gxPLDevice device, const char name, int index, const char *value)
	Set a item value at a given index. More...

Typedefs
typedef struct _gxPLDeviceConfigItem	gxPLDeviceConfigItem
	Describe a element of configuration.

typedef void(*	gxPLDeviceConfigListener) (gxPLDevice , void )
	Device configuration changed listener The end-user can add listener functions that will be called each time the device configuration will change. .

Function Documentation

gxPLDevice* gxPLAppAddConfigurableDevice	(	gxPLApplication *	app,
		const char *	vendor_id,
		const char *	device_id,
		const char *	filename
	)

Adds a new configurable device.

Parameters

app	pointer to a gxPLApplication object
vendor_id	pointer to the vendor id
device_id	pointer to the device id
filename	pointer to the config filename

Returns: pointer on the configurable device, NULL if error occurs

Examples:: logger/gxpl-logger.c.

const char* gxPLDeviceConfigFilenameGet ( const gxPLDevice * device )

Return the installed config file, if any.

see gxPLAppAddConfigurableDevice()

Parameters

device pointer on the configurable device

Returns: filename, NULL if error occurs

int gxPLDeviceConfigItemAdd	(	gxPLDevice *	device,
		const char *	name,
		gxPLConfigurableType	type,
		int	max_values
	)

Add a new configurable.

If the item already exists, -1 is returned and it's not added or altered.

Parameters

device	pointer on the configurable device
name	name of the item
type	type of the item
max_values	maximum number of values for this item

Returns: 0, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLDeviceConfigItemClearAll ( gxPLDevice * device )

Clear all configurable values out.

The configurable definitions remain intact.

Parameters

device pointer on the configurable device

Returns: 0, -1 if an error occurs

gxPLDeviceConfigItem* gxPLDeviceConfigItemFind	(	const gxPLDevice *	device,
		const char *	name
	)

Search for a configurable.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: the item, NULL if not found or error occurs

int gxPLDeviceConfigItemRemove	(	gxPLDevice *	device,
		const char *	name
	)

Remove a configurable.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: 0, -1 if an error occurs

int gxPLDeviceConfigItemRemoveAll ( gxPLDevice * device )

Remove all configurables.

Parameters

device pointer on the configurable device

Returns: 0, -1 if an error occurs

int gxPLDeviceConfigListenerAdd	(	gxPLDevice *	device,
		gxPLDeviceConfigListener	listener,
		void *	udata
	)

Add a device config changed listener.

Parameters

device	pointer on the configurable device
listener
udata	pointer to the data passed to the listener

Returns: 0, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLDeviceConfigListenerRemove	(	gxPLDevice *	device,
		gxPLDeviceConfigListener	listener
	)

Remove a config changed listener.

Parameters

device	pointer on the configurable device
listener

Returns: 0, -1 if an error occurs

int gxPLDeviceConfigSave ( const gxPLDevice * device )

Save out the current configuration.

Parameters

device

Returns: 0, -1 if error occurs

int gxPLDeviceConfigValueAdd	(	gxPLDevice *	device,
		const char *	name,
		const char *	value
	)

Add a device item value.

If there are already values this is added to it, up to the limit defined for the configurable. If the item is "full", then the value is discarded.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: 0, -1 if an error occurs

int gxPLDeviceConfigValueClearAll	(	gxPLDevice *	device,
		const char *	name
	)

Clear values for a given configurable.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: 0, -1 if an error occurs

int gxPLDeviceConfigValueCount	(	const gxPLDevice *	device,
		const char *	name
	)

Return the number of values for a given configurable.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: 0, -1 if an error occurs

const char* gxPLDeviceConfigValueGet	(	gxPLDevice *	device,
		const char *	name
	)

Return the value of the first/only index for an item.

Parameters

device	pointer on the configurable device
name	name of the item

Returns: the value, NULL if none or error occurs

Examples:: logger/gxpl-logger.c.

const char* gxPLDeviceConfigValueGetAt	(	gxPLDevice *	device,
		const char *	name,
		int	index
	)

Return the value at the given index.

Parameters

device	pointer on the configurable device
name	name of the item
index	index of the value to set

Returns: if the value is NULL of the index is out of range, NULL is returned

int gxPLDeviceConfigValueSet	(	gxPLDevice *	device,
		const char *	name,
		const char *	value
	)

Simple form to set first/only value in an item.

Parameters

device	pointer on the configurable device
name	name of the item
value	value to set

Returns: 0, -1 if an error occurs

Examples:: logger/gxpl-logger.c.

int gxPLDeviceConfigValueSetAt	(	gxPLDevice *	device,
		const char *	name,
		int	index,
		const char *	value
	)

Set a item value at a given index.

If that index is above the actual number of values, the value is appeneded (i.e. may not be the same index as passed)

Parameters

device	pointer on the configurable device
name	name of the item
index	index of the value to set
value	value to set

Returns: 0, -1 if an error occurs

Detailed Description

Data Structures

Functions

Typedefs

Function Documentation