AudioScience HPI Version_4.23.0
Functions

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.
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:
0OK
HPI_ERROR_INVALID_OBJ_INDEXThe URI doesn't correspond to any known object
HPI_ERROR_INVALID_RESOURCEThe URI must start with "hpi://"
Parameters:
uriURI of HPI object, Network
hObject 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_INDEXthe 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:
hobject handle from HPI_Object_UriToHandle()
inforeturns 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:
hObjectObject handle.
typetype of entity to unpack.
rolerole of the entity to unpack.
valuepassed in pointer to data buffer where result is copied. May be set to NULL to retreive size and item count information.
value_sizesize in bytes of the passed in buffer. This is also updated and returned.
value_countnumber 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:
hObjectObject handle.
rReturned 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:
hMixerMixer handle.
blockBlock handle.
paramsArray of parameter handles (may be set to NULL).
param_countParameter 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:
hMixerMixer handle.
wSrcNodeTypeSource node type i.e. HPI_SOURCENODE_OSTREAM.
wSrcNodeTypeIndexIndex of particular source node type i.e. the 2nd HPI_SOURCENODE_OSTREAM would be specified as index=1.
wDstNodeTypeDestination node type i.e. HPI_DESTNODE_LINEOUT.
wDstNodeTypeIndexIndex of particular source node type i.e. the 3rd HPI_DESTNODE_LINEOUT would be specified as index=2
block_nameName of the block to find.
phBlockReturned 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:
hMixerMixer handle.
hBlockBlock handle.
parameter_nameName of the parameter to return.
phParameterReturned 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_INDEXthe 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:
hobject handle from HPI_Object_UriToHandle()
valuereturns 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:
hobject handle from HPI_Object_UriToHandle()
valueentity, 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:
hobject handle from HPI_Object_UriToHandle()
typebase type of *value
countnumber of items of the base type
valuevalue retrieved from object
value_sizesize 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:
hobject handle from HPI_Object_UriToHandle()
typebase type of *value
countnumber of items of the base type
valuevalue to be set in object
value_sizesize 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:
memPointer to the memory to be freed.