Universal Control

A universal control is a control type that supports abstract mechanisms for accessing data, thereby making it capable of representing any controllable parameter. More...

Functions
hpi_err_t	HPI_Universal_Info (const hpi_hsubsys_t *phSubSys, hpi_handle_t hC, struct hpi_entity **info)
	Retrieve information associated with an universal control.
hpi_err_t	HPI_Universal_Get (const hpi_hsubsys_t *phSubSys, hpi_handle_t hC, struct hpi_entity **value)
	Returns the current value of an universal control as an entity.
hpi_err_t	HPI_Universal_Set (const hpi_hsubsys_t *phSubSys, hpi_handle_t hC, struct hpi_entity *value)
	Set the current value of an universal control.

---

Detailed Description

A universal control is a control type that supports abstract mechanisms for accessing data, thereby making it capable of representing any controllable parameter.

Multiple related universal controls are created in sequence to form a block. For example, a tuner block might use 2 universal controls to represent the band and the frequency of the tuner. Carrying this description further, the band and frequency would be referred to as parameters of the tuner block.

A header universal control is used to name the block and specify the number and location of parameters that follow. The universal control list for the above tuner example looks like:

Index	Name	Description
n	Tuner	Block header, count = 2
n+1	Band	Parameter for the band
n+2	Frequency	Parameter for the frequency

A call to HPI_MixerGetControl() will return only the first control of type HPI_CONTROL_UNIVERSAL.

Need to add stuff about how to unpack the remaining parameter controls...

---

Function Documentation

hpi_err_t HPI_Universal_Info	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hC,
		struct hpi_entity **	info
	)

Retrieve information associated with an universal control.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
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.

See also:

HPI_Entity_Free()

Returns:

0 on success, or one of the HPI_ERROR_CODES.

Referenced by HPI_Object_BlockParameters(), HPI_Object_GetInfo(), and HPI_Object_GetRole().

hpi_err_t HPI_Universal_Get	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hC,
		struct hpi_entity **	value
	)

Returns the current value of an universal control as an entity.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
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.

See also:

HPI_Entity_Free()

Returns:

0 on success, or one of the HPI_ERROR_CODES.

hpi_err_t HPI_Universal_Set	(	const hpi_hsubsys_t *	phSubSys,
		hpi_handle_t	hC,
		struct hpi_entity *	value
	)

Set the current value of an universal control.

Parameters:

phSubSys	Vestigial subsys handle (unused), may be set to NULL
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.