udi_instance_attr_set(3udi)


Set a driver instance attribute value

SYNOPSIS

#include <udi.h>

void udi_instance_attr_set {

	udi_instance_attr_set_call_t *callback,

	udi_cb_t *gcb,

	const char *attr_name,

	udi_ubit32_t child_ID,

	const void *attr_value,

	udi_size_t attr_length,

	udi_ubit8_t attr_type );
 
typedef void udi_instance_attr_set_call_t (

	udi_cb_t *gcb,

	udi_status_t status );
 

ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".

attr_name is the name of the attribute whose value is to be set.

child_ID is the child ID associated with the specific child instance for which this attribute is to be set if it is a parent-visible attribute (prefix character `@').

For parent-visible attributes, this argument must match a child_ID from a previous udi_enumerate_ack that has not been unenumerated; it is ignored for other types of attributes.

attr_value is a pointer to the attribute value to set. attr_value must be NULL if and only if attr_length is 0.

attr_length is the length of the value pointed to by attr_value.

attr_type is the type specifier for the attribute value. See udi_instance_attr_type_t for details. UDI_ATTR_FILE is not allowed with udi_instance_attr_set. attr_type must be UDI_ATTR_NONE if and only if attr_length is zero.

DESCRIPTION The udi_instance_attr_set function is used to set the value of a driver-instance attribute. The attribute to set is specified by attr_name and may be either a persistent or a volatile attribute depending on the attribute type (as indicated by a prefix character).

The attr_value, attr_length, and attr_type combine to specify the attribute value. If the attribute does not presently exist, it is created. If the current attribute type is different than attr_type, the attribute type will be changed to the newly specified type. If the attribute length attr_length is specified as zero, the attribute may be deleted from the database. In general, a zero-length attribute is indistinguishable from a non-existent attribute.

The length of the attribute value specified by attr_value and attr_length must not exceed the maximum length specified by the max_instance_attr_len member of the udi_limits_t structure.

The status value indicates the success or failure of the attribute modification operation.

The udi_instance_attr_set service call must not be used with the UDI_ATTR_FILE attribute type.

WARNINGS Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Standard Calling Sequences".

Use of the attr_name and attr_value parameters must conform to the rules described in Section 5.2.1.1, "Using Memory Pointers with Asynchronous Service Calls".

STATUS VALUE UDI_OK the attribute value was successfully modified.

UDI_STAT_RESOURCE_UNAVAIL the persistent storage database is full and this attribute could not be created or set in the database. The driver is not expected to retry the operation; it should consider this a permanent failure.

UDI_STAT_NOT_SUPPORTED the current environment does not allow modification of the persistent storage database. This error can only occur with persistent attributes.

REFERENCES udi_instance_attr_get, UDI_INSTANCE_ATTR_DELETE, udi_limits_t


UDI Core Specification Contents