Generic Device property control

This contains the function set necessary to control arbitrary device properties.

Functions
int APIDECL	dcDevice_GetRoot (DEVICE d, TOKEN *t)
	Get root namespace descriptor token of current device.
int APIDECL	dcProperty_Select (DEVICE d, TOKEN parent, TOKEN prev, TOKEN *out)
	Select a property in the property and feature hierarchy.
int APIDECL	dcProperty_ParseName (DEVICE d, const char *propname, TOKEN *out)
	Get a property handle (TOKEN) by name.
int APIDECL	dcProperty_GetProto (DEVICE d, TOKEN p, DCValue *proto)
	Get a property prototype by token This function is needed to query a property by token.
int APIDECL	dcProperty_GetName (DEVICE d, TOKEN p, DCValue *name)
	Get name of a property which is only known by token.
int APIDECL	dcDevice_GetProperty (DEVICE d, TOKEN p, DCValue *value)
	Get the property value of the device.
int APIDECL	dcDevice_SetProperty (DEVICE d, TOKEN p, DCValue *value)
	Set the value of a device property.

---

Function Documentation

int APIDECL dcDevice_GetProperty	(	DEVICE	d,
		TOKEN	p,
		DCValue *	value
	)

By default, a property value is owned by the caller, i.e. in case of a dynamic string property, the caller is responsible for allocating the proper memory and initializing the DCValue pointer field. See Section Property concept.

Parameters:

	d	The DEVICE handle of the device
	p	The property token whose value is to be requested
	value	Pointer to a DCValue which contains the property value after successful return of this function. Note that in case of a non static string property, the property value must be initialized first.

Returns:

A standard return code

Examples:

master.c.

Referenced by Property::getValue().

int APIDECL dcDevice_GetRoot	(	DEVICE	d,
		TOKEN *	t
	)

This function always returns a valid token.

Returns:

The root descriptor token of the device d

Examples:

master.c.

Referenced by Device::getName(), and Device::getRoot().

int APIDECL dcDevice_SetProperty	(	DEVICE	d,
		TOKEN	p,
		DCValue *	value
	)

Parameters:

	d	The DEVICE handle of the device
	p	The property token whose value is to be requested
	value	Pointer to a DCValue containing the value to be set.

Returns:

The standard return code

Examples:

master.c.

Referenced by Property::setValue().

int APIDECL dcProperty_GetName	(	DEVICE	d,
		TOKEN	p,
		DCValue *	name
	)

Parameters:

	d	The DEVICE handle of the device
	p	The property token whose type is to be queried
	name	DCValue which must be intialized as shown below

In case of a remote device, name must be preinitialized, because the string is owned by the caller, like with any DCValue. This is done as follows:

        char propname[32];
        DCValue v; v.value.p = propname; v.len = sizeof(propname);

On return without error, the property name is stored in name.value.p. If the string reserved was too small to fit the property name, DCERR_PROPERTY_SIZE_MATCH is returned.

When specifying DC_PORT_ROOT for d, v.value.p does not have to be preinitialized and contains a pointer to a static string on return.

Examples:

master.c.

Referenced by Device::getName(), and Property::getName().

int APIDECL dcProperty_GetProto	(	DEVICE	d,
		TOKEN	p,
		DCValue *	proto
	)

Parameters:

	d	The DEVICE handle of the device
	p	The property token whose type is to be queried
	proto	Uninitialized DCValue

On return without error, the property type can be read from proto.type, and the size from proto.len. Note: Reading the size only works on static buffers. On handled buffers, the size is a priori not known. To obtain the size of a handled buffer, an attempt for dcDevice_GetProperty() must be made on the buffer property. When a DCERR_PROPERTY_SIZE_MATCH is returned, the size can be read from proto.len.

Examples:

master.c.

Referenced by Property::getProto().

int APIDECL dcProperty_ParseName	(	DEVICE	d,
		const char *	propname,
		TOKEN *	out
	)

Parameters:

	d	The DEVICE handle of the device
	propname	Pointer to a string containing the property name
	out	Pointer to the token to be filled in

Before v0.21, relative namespaces were not supported, always the full property name had to be passed. New with this function: When 'propname' begins with a '.', the name is regarded as relative to a parent property. The TOKEN pointed to by the 'out' pointer must be preinitialized by that parent property token.

Examples:

master.c.

Referenced by Device::getProperty().

int APIDECL dcProperty_Select	(	DEVICE	d,
		TOKEN	parent,
		TOKEN	prev,
		TOKEN *	out
	)

This function is used to query a property inside the property hierarchy which is organized in a tree. A property can have children and has always a parent, except if it is the root node.

Quick overview: To select the first child of a node, use:

     error = dcProperty_Select(d, node, node, &child); 

To select the next children of that node:

     error = dcProperty_Select(d, node, child, &next); 

When the dummy device DC_PORT_ROOT is specified, this function will operate on the local Hub/Port structure. See Section Hubs and Port access.

Parameters:

	d	The DEVICE handle of the device (see special case of DC_PORT_ROOT)
	parent	The parent node to be queried
	prev	The node whose following (next) node shall be selected If the parent node is specified, its first children is selected.
	out	Pointer to token whose value will be filled in with the selected node token (next or children)

Examples:

master.c.