Object

Starting with driver 4.08, AudioScience has begun representing certain new controls as abstract objects. More...

Functions
hpi_err_t	HPI_Object_UriToHandle (const char *uri, hpi_handle_t *h)
	Get an object handle given the object's URI. More...
hpi_err_t	HPI_Object_GetInfoEntity (hpi_handle_t h, struct hpi_entity **info)
	Get the complete information entity for an object addressed by handle. More...
hpi_err_t	HPI_Object_GetInfo (hpi_handle_t hObject, enum e_entity_type type, enum e_entity_role role, void *value, size_t *value_size, size_t *value_count)
	Get information about an object. More...
hpi_err_t	HPI_Object_GetRole (hpi_handle_t hObject, enum e_entity_role *r)
	Get the object role. More...
hpi_err_t	HPI_Object_BlockParameters (hpi_handle_t hMixer, hpi_handle_t block, hpi_handle_t *params, size_t *param_count)
	Given a block handle, return a list of parameter object handles. More...
hpi_err_t	HPI_Object_BlockHandle (hpi_handle_t hMixer, uint16_t wSrcNodeType, uint16_t wSrcNodeTypeIndex, uint16_t wDstNodeType, uint16_t wDstNodeTypeIndex, const char *block_name, hpi_handle_t *phBlock)
	Given block location information and name, fetch an object handle for the block. More...
hpi_err_t	HPI_Object_ParameterHandle (hpi_handle_t hMixer, hpi_handle_t hBlock, const char *parameter_name, hpi_handle_t *phParameter)
	Given a block handle and parameter name, fetch an object handle for the specified parameter. More...
hpi_err_t	HPI_Object_GetValueEntity (hpi_handle_t h, struct hpi_entity **value)
	Get the value entity of an object addressed by its handle. More...
hpi_err_t	HPI_Object_SetValueEntity (hpi_handle_t h, const struct hpi_entity *value)
	Set the value entity of an object addressed by its handle. More...
hpi_err_t	HPI_Object_GetValue (hpi_handle_t h, enum e_entity_type type, size_t count, void *value, size_t value_size)
	Retrieve an object's value. More...
hpi_err_t	HPI_Object_SetValue (hpi_handle_t h, enum e_entity_type type, size_t count, const void *value, size_t value_size)
	Set an object's value. More...
void	HPI_MemFree (void *mem)
	Free memory allocated by a previous HPI call. More...

Detailed Description

Starting with driver 4.08, AudioScience has begun representing certain new controls as abstract objects.

Each equivalent of a "knob" is an object of type parameter. Parameters that logically belong together are grouped into an object of type block.

Blocks are represented as HPI controls of type HPI_CONTROL_UNIVERSAL. An application can look for a specific block by using HPI_Object_BlockHandle(). Parameters are also represented as HPI controls of type HPI_CONTROL_UNIVERSAL and HPI_Object_ParameterHandle() should be be used to locate a specific parameter within a block.

See Audio Delay for an example of block and parameter usage.

Function Documentation

HPI_Object_UriToHandle()

hpi_err_t HPI_Object_UriToHandle	(	const char *	uri,
		hpi_handle_t *	h
	)

Get an object handle given the object's URI.

For a complete list of valid URIs, see Network.

Usage:

hpi_handle_t h;
int enable;
err = HPI_Object_UriToHandle("hpi:///subsystem/network/enable",  &h);
err = HPI_Object_GetValue(h, entity_type_int, 1, &enable, sizeof(enable) );
enable = 1;
err = HPI_Object_SetValue(h, entity_type_int, 1,  &enable, sizeof(enable));

Return values

0	OK
HPI_ERROR_INVALID_OBJ_INDEX	The URI doesn't correspond to any known object
HPI_ERROR_INVALID_RESOURCE	The URI must start with "hpi://"

Parameters

uri	URI of HPI object, Network
h	Object handle

HPI_Object_GetInfoEntity()

hpi_err_t HPI_Object_GetInfoEntity	(	hpi_handle_t	h,
		struct hpi_entity **	info
	)

Get the complete information entity for an object addressed by handle.

Return values

HPI_ERROR_INVALID_OBJ_INDEX

the handle doesnt correspond to an object type that might support this function.

Note

HPI_Entity_Free() must always be called on info, even if error is returned, to ensure an allocated memory is freed.

Parameters

h	object handle from HPI_Object_UriToHandle()
info	returns address of allocated info entity

HPI_Object_GetInfo()

hpi_err_t HPI_Object_GetInfo	(	hpi_handle_t	hObject,
		enum e_entity_type	type,
		enum e_entity_role	role,
		void *	value,
		size_t *	value_size,
		size_t *	value_count
	)

Get information about an object.

Parameters

hObject	Object handle.
type	type of entity to unpack.
role	role of the entity to unpack.
value	passed in pointer to data buffer where result is copied. May be set to NULL to retreive size and item count information.
value_size	size in bytes of the passed in buffer. This is also updated and returned.
value_count	number of items. This is always updated and returned.

Returns

0 on success, or one of the HPI_ERROR_CODES.

HPI_Object_GetRole()

hpi_err_t HPI_Object_GetRole	(	hpi_handle_t	hObject,
		enum e_entity_role *	r
	)

Get the object role.

Returns

0 on success, or one of the HPI_ERROR_CODES.

Parameters

hObject	Object handle.
r	Returned role.

HPI_Object_BlockParameters()

hpi_err_t HPI_Object_BlockParameters	(	hpi_handle_t	hMixer,
		hpi_handle_t	block,
		hpi_handle_t *	params,
		size_t *	param_count
	)

Given a block handle, return a list of parameter object handles.

Returns

0 on success, or one of the HPI_ERROR_CODES.

Parameters

hMixer	Mixer handle.
block	Block handle.
params	Array of parameter handles (may be set to NULL).
param_count	Parameter count. This is always updated on return to reflect the parameter count.

HPI_Object_BlockHandle()

hpi_err_t HPI_Object_BlockHandle	(	hpi_handle_t	hMixer,
		uint16_t	wSrcNodeType,
		uint16_t	wSrcNodeTypeIndex,
		uint16_t	wDstNodeType,
		uint16_t	wDstNodeTypeIndex,
		const char *	block_name,
		hpi_handle_t *	phBlock
	)

Given block location information and name, fetch an object handle for the block.

Returns

0 on success, or one of the HPI_ERROR_CODES.

Parameters

hMixer	Mixer handle.
wSrcNodeType	Source node type i.e. HPI_SOURCENODE_OSTREAM.
wSrcNodeTypeIndex	Index of particular source node type i.e. the 2nd HPI_SOURCENODE_OSTREAM would be specified as index=1.
wDstNodeType	Destination node type i.e. HPI_DESTNODE_LINEOUT.
wDstNodeTypeIndex	Index of particular source node type i.e. the 3rd HPI_DESTNODE_LINEOUT would be specified as index=2
block_name	Name of the block to find.
phBlock	Returned object handle.

References HPI_ERROR_INVALID_CONTROL_VALUE.

HPI_Object_ParameterHandle()

hpi_err_t HPI_Object_ParameterHandle	(	hpi_handle_t	hMixer,
		hpi_handle_t	hBlock,
		const char *	parameter_name,
		hpi_handle_t *	phParameter
	)

Given a block handle and parameter name, fetch an object handle for the specified parameter.

Returns

0 on success, or one of the HPI_ERROR_CODES.

Parameters

hMixer	Mixer handle.
hBlock	Block handle.
parameter_name	Name of the parameter to return.
phParameter	Returned object handle.

References HPI_ERROR_INVALID_CONTROL_VALUE.

HPI_Object_GetValueEntity()

hpi_err_t HPI_Object_GetValueEntity	(	hpi_handle_t	h,
		struct hpi_entity **	value
	)

Get the value entity of an object addressed by its handle.

Return values

HPI_ERROR_INVALID_OBJ_INDEX

the handle doesnt correspond to an object type that might support this function.

Note

HPI_Entity_Free() must always be called on value, even if error is returned, to ensure an allocated memory is freed.

Parameters

h	object handle from HPI_Object_UriToHandle()
value	returns address of allocated value entity

References hpi_handle::adapterIndex, and hpi_handle::objType.

Referenced by HPI_Object_GetValue().

HPI_Object_SetValueEntity()

hpi_err_t HPI_Object_SetValueEntity	(	hpi_handle_t	h,
		const struct hpi_entity *	value
	)

Set the value entity of an object addressed by its handle.

Parameters

h	object handle from HPI_Object_UriToHandle()
value	entity, with role=entity_role_value

References hpi_handle::adapterIndex, and hpi_handle::objType.

Referenced by HPI_Object_SetValue().

HPI_Object_GetValue()

hpi_err_t HPI_Object_GetValue	(	hpi_handle_t	h,
		enum e_entity_type	type,
		size_t	count,
		void *	value,
		size_t	value_size
	)

Retrieve an object's value.

Parameters

h	object handle from HPI_Object_UriToHandle()
type	base type of *value
count	number of items of the base type
value	value retrieved from object
value_size	size in bytes of *value

References HPI_Entity_CopyValueFrom(), HPI_Entity_Free(), and HPI_Object_GetValueEntity().

HPI_Object_SetValue()

hpi_err_t HPI_Object_SetValue	(	hpi_handle_t	h,
		enum e_entity_type	type,
		size_t	count,
		const void *	value,
		size_t	value_size
	)

Set an object's value.

Parameters

h	object handle from HPI_Object_UriToHandle()
type	base type of *value
count	number of items of the base type
value	value to be set in object
value_size	size in bytes of *value

References entity_role_value, HPI_Entity_AllocAndPack(), HPI_Entity_Free(), and HPI_Object_SetValueEntity().

HPI_MemFree()

void HPI_MemFree

(

void *

mem

)

Free memory allocated by a previous HPI call.

Parameters

mem	Pointer to the memory to be freed.