Universal Control
[Mixer and Controls]

Universal controls. More...

Functions
static HPI_ERR	hpi_entity_check_type (const enum e_entity_type t)
	Check if the type is a valid value for corresponding the field in the hpi_entity struct.
static HPI_ERR	hpi_entity_check_role (const enum e_entity_role r)
	Check if the role is a valid value for the corresponding field in the hpi_entity struct.
static HPI_ERR	HPI_Entity_GetNext (struct hpi_entity *entity, int recursive_flag, void *guard_p, struct hpi_entity **next)
	Get the next Entity in a sequence of entities.
HPI_ERR	HPI_Entity_FindNext (struct hpi_entity *container_entity, enum e_entity_type type, enum e_entity_role role, int recursive_flag, struct hpi_entity **current_match)
	Search for an entity with the given _type_ and _role_ in a container entity.
void	HPI_Entity_Free (struct hpi_entity *entity)
	Free an hpi_entity allocated by HPI_Universal_* and HPI_Entity_* functions.
static HPI_ERR	HPI_Entity_AllocAndCopy (struct hpi_entity *src, struct hpi_entity **dst)
	Allocates an appropriately sized buffer and copies the src entity into it.
HPI_ERR	HPI_Universal_Info (const HPI_HSUBSYS *phSubSys, HPI_HCONTROL hC, struct hpi_entity **info)
	Retrieve information associated with an universal control.
HPI_ERR	HPI_Universal_Get (const HPI_HSUBSYS *phSubSys, HPI_HCONTROL hC, struct hpi_entity **value)
	Returns the current value of an universal control as an entity.
HPI_ERR	HPI_Universal_Set (const HPI_HSUBSYS *phSubSys, HPI_HCONTROL hC, struct hpi_entity *value)
	Set the current value of an universal control.
HPI_ERR	HPI_Entity_AllocAndPack (const enum e_entity_type type, const size_t item_count, const enum e_entity_role role, void *value, struct hpi_entity **entity)
	Allocate and initialize an entity with the provided parameters.
HPI_ERR	HPI_Entity_CopyValueFrom (struct hpi_entity *entity, enum e_entity_type type, size_t item_count, void *value_dst_p)
	Copies item_count items from the Entity's value array into *value_dst_p.
HPI_ERR	HPI_Entity_Unpack (struct hpi_entity *entity, enum e_entity_type *type, size_t *item_count, enum e_entity_role *role, void **value)
	Extracts information from an entity into the specified locations.

---

Detailed Description

Universal controls.

---

Function Documentation

static HPI_ERR hpi_entity_check_type (  const enum e_entity_type  t  )  [inline, static]

Check if the type is a valid value for corresponding the field in the hpi_entity struct. It is not possible to restrict the check to the values defined by the enum e_entity_type because it would prevent the functions from accepting unknown types defined in subsequent versions Returns: 0 on success or HPI_ERROR_ENTITY_TYPE_INVALID

static HPI_ERR hpi_entity_check_role (  const enum e_entity_role  r  )  [inline, static]

Check if the role is a valid value for the corresponding field in the hpi_entity struct. It is not possible to restrict the check to the values defined by the enum e_entity_role because it would prevent the functions from accepting unknown roles defined in subsequent versions Returns: 0 on success or HPI_ERROR_ENTITY_ROLE_INVALID

static HPI_ERR HPI_Entity_GetNext (  struct hpi_entity *  entity, int  recursive_flag, void *  guard_p, struct hpi_entity **  next )  [static]

Get the next Entity in a sequence of entities. The variable pointed by next will be updated with the address of the next Entity or set to NULL if no more entities are found. If the current entity is a sequence and the recursive_flag is non-zero then the first item in the sequence is returned. If the current entity is a sequence and the recursive_flag is zero then the first entity after the sequence is returned. In all other cases the next entity is returned. Parameters: entity  Pointer to the current entity. next  Pointer to the variable where the pointer to the next entity will be copied. If no next entity is found *next is set to NULL. recursive_flag  Indicate if the next entity should be obtained using a depth-first search guard_p  Pointer to the last valid memory location of the entities buffer. No Entity spanning beyond this location will be returned. This typically means the the guard_p is computed from a container entity that has many entities in it and is therefore set to span all the entities that are being stepped through with each call. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Entity_FindNext (  struct hpi_entity *  container_entity, enum e_entity_type  type, enum e_entity_role  role, int  recursive_flag, struct hpi_entity **  current_match )

Search for an entity with the given _type_ and _role_ in a container entity. Search for an entity with the given type and role in container_entity. The search starts with the first entity inside the container_entity. If container_entity is not a sequence then the function will return immediately. The variable pointed by current_match will be updated with the address of the next Entity or set to NULL if no more entities are found. If current_match is not NULL upon call then the search resumes from the entity following current_match. The recursive_flag is honored so if current match is a sequence and recursive_flag is non-zero then searching will start with the first item in the sequence. Parameters: container_entity  Pointer to the container entity to be searched. type  Entity type selector value or entity_type_null. If a non-null type is specified then the returned match will have this type. If a null type is specified then the type of the entity is ignored when searching. role  Entity role selector value or entity_role_null. If a non-null role is specified then the returned match will have this type. If a null role is specified then the role of the entity is ignored when searching. current_match  Pointer to the variable where the pointer to the next matching entity will be copied. If no matching entity is found *current_match is set to NULL. recursive_flag  Indicates the next entity should be obtained using a depth-first search. When the recursive_flag is set, the search starts at the current position in the entity tree and proceeds through the list of entity objects. Every time a sequence is encountered the new sequence is searched until the bottom of the tree is reached at which point the search backtracks. For example, the tree below would be searched in order A,B,C,D,E,F,G,H if the recursive_flag is set. If the recursive_flag is not set the search order becomes A,B,C,H. |------[A - entity of type sequence] |------[B] |------[C- entity of type sequence] | |---[D] | |---[E- entity of type sequence] | |---[F] | |---[G] | |------[H] Returns: 0 on success, or one of the HPI_ERROR_CODES.

void HPI_Entity_Free (  struct hpi_entity *  entity  )

Free an hpi_entity allocated by HPI_Universal_* and HPI_Entity_* functions. Parameters: entity  Pointer to the entity to be freed

static HPI_ERR HPI_Entity_AllocAndCopy (  struct hpi_entity *  src, struct hpi_entity **  dst )  [static]

Allocates an appropriately sized buffer and copies the src entity into it. The newly allocated buffer is returned in dst. Parameters: src  Pointer to the original entity to be copied. dst  Pointer to the newly allocated buffer where the copy is returned. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Universal_Info (  const HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  hC, struct hpi_entity **  info )

Retrieve information associated with an universal control. Parameters: phSubSys  HPI subsystem handle. hC  Control handle. info  Location where a pointer to the newly allocated buffer is returned. Info must always be freed by the caller because it may be allocated and contain a (partial) result even if the function returns an error. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Universal_Get (  const HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  hC, struct hpi_entity **  value )

Returns the current value of an universal control as an entity. Parameters: phSubSys  HPI subsystem handle. hC  Control handle. value  Location where a pointer to the newly allocated buffer is returned. value must always be freed by the caller because it may be allocated and contain a (partial) result even if the function returns an error. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Universal_Set (  const HPI_HSUBSYS *  phSubSys, HPI_HCONTROL  hC, struct hpi_entity *  value )

Set the current value of an universal control. Parameters: phSubSys  HPI subsystem handle. hC  Control handle. value  Pointer to the entity containing the new value for the universal control. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Entity_AllocAndPack (  const enum e_entity_type  type, const size_t  item_count, const enum e_entity_role  role, void *  value, struct hpi_entity **  entity )

Allocate and initialize an entity with the provided parameters. Parameters: type  Entity type. item_count  Number of instances of _type_ contained in the _value_ array. role  Entity role. value  Pointer to an array of _type_ with at least _item_count_ elements. entity  Location where a pointer to the newly allocated buffer containing the entity is saved. The buffer must be freed by the caller using HPI_Entity_Free() even when the call returns an error. Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Entity_CopyValueFrom (  struct hpi_entity *  entity, enum e_entity_type  type, size_t  item_count, void *  value_dst_p )

Copies item_count items from the Entity's value array into *value_dst_p. If type is different from the type of the entity no value is copied and an error is returned. If the item_count is larger than the size the Entitiy's value array then no value is copied and an error is returned. Parameters: entity  Pointer to the entity to copy values from. type  Type of the variable pointed by value_dst_p. item_count  Number of items to copy. This should match the storage associated with value_dst_p. value_dst_p  Pointer to output buffer Returns: 0 on success, or one of the HPI_ERROR_CODES.

HPI_ERR HPI_Entity_Unpack (  struct hpi_entity *  entity, enum e_entity_type *  type, size_t *  item_count, enum e_entity_role *  role, void **  value )

Extracts information from an entity into the specified locations. Parameters: entity  The entity being unpacked. type  Pointer to the variable where the type of the entity is copied to or NULL. item_count  Pointer to the variable where the number of instances of _type_ contained in the entity is copied to or NULL. role  Pointer to the variable where the role of the entity is copied to or NULL. value  Pointer to the location where a pointer to the value array of the entity is copied. Note: the value array of the entity is not copied, a pointer to its location is copied into the variable pointed by value. Returns: 0 on success, or one of the HPI_ERROR_CODES.

---