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.
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.
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.
hpi_err_t	HPI_Object_GetRole (hpi_handle_t hObject, enum e_entity_role *r)
	Get the object role.
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.
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.
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.
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.
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.
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.
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.
void	HPI_MemFree (void *mem)
	Free memory allocated by a previous HPI call.

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_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

References HPI_ERROR_INVALID_OBJ_INDEX, HPI_ERROR_INVALID_RESOURCE, and HPI_IndexesToHandle().

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

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

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.

References entity_type_cstring, HPI_Entity_FindNext(), HPI_Entity_Free(), HPI_Entity_Unpack(), HPI_ERROR_ENTITY_ITEM_COUNT, HPI_ERROR_ENTITY_TYPE_MISMATCH, and HPI_Universal_Info().

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.

References HPI_Entity_Free(), HPI_Entity_GetRole(), and HPI_Universal_Info().

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.

References entity_role_block, entity_role_value, entity_type_reference, HPI_Entity_FindNext(), HPI_Entity_Free(), HPI_Entity_GetRole(), HPI_Entity_Unpack(), HPI_ERROR_ENTITY_ITEM_COUNT, HPI_ERROR_ENTITY_TYPE_MISMATCH, HPI_MixerGetControlByIndex(), and HPI_Universal_Info().

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_CONTROL_UNIVERSAL, HPI_ERROR_INVALID_CONTROL_VALUE, and HPI_IndexesToHandle().

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, and HPI_IndexesToHandle().

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, HPI_ERROR_INVALID_OBJ_INDEX, hpi_handle::objIndex, and hpi_handle::objType.

Referenced by HPI_Object_GetValue().

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, HPI_ERROR_INVALID_OBJ_INDEX, hpi_handle::objIndex, and hpi_handle::objType.

Referenced by HPI_Object_SetValue().

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_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().

void HPI_MemFree ( void * mem )

Free memory allocated by a previous HPI call.

Parameters:

mem	Pointer to the memory to be freed.

Object

Functions

Detailed Description

Function Documentation