ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Typedefs | Functions
High level Control Interface
Control Interface

Typedefs

typedef struct _snd_hctl_elem snd_hctl_elem_t
typedef struct _snd_hctl snd_hctl_t
typedef int(* snd_hctl_compare_t )(const snd_hctl_elem_t *e1, const snd_hctl_elem_t *e2)
 Compare function for sorting HCTL elements.
typedef int(* snd_hctl_callback_t )(snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem)
 HCTL callback function.
typedef int(* snd_hctl_elem_callback_t )(snd_hctl_elem_t *elem, unsigned int mask)
 HCTL element callback function.

Functions

int snd_hctl_compare_fast (const snd_hctl_elem_t *c1, const snd_hctl_elem_t *c2)
 A "don't care" fast compare functions that may be used with snd_hctl_set_compare.
int snd_hctl_open (snd_hctl_t **hctl, const char *name, int mode)
 Opens an HCTL.
int snd_hctl_open_ctl (snd_hctl_t **hctlp, snd_ctl_t *ctl)
 Opens an HCTL.
int snd_hctl_close (snd_hctl_t *hctl)
 close HCTL handle
int snd_hctl_nonblock (snd_hctl_t *hctl, int nonblock)
 set nonblock mode
int snd_hctl_poll_descriptors_count (snd_hctl_t *hctl)
 get count of poll descriptors for HCTL handle
int snd_hctl_poll_descriptors (snd_hctl_t *hctl, struct pollfd *pfds, unsigned int space)
 get poll descriptors
int snd_hctl_poll_descriptors_revents (snd_hctl_t *ctl, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
 get returned events from poll descriptors
unsigned int snd_hctl_get_count (snd_hctl_t *hctl)
 Get number of loaded elements for an HCTL.
int snd_hctl_set_compare (snd_hctl_t *hctl, snd_hctl_compare_t hsort)
 Change HCTL compare function and reorder elements.
snd_hctl_elem_tsnd_hctl_first_elem (snd_hctl_t *hctl)
 get first element for an HCTL
snd_hctl_elem_tsnd_hctl_last_elem (snd_hctl_t *hctl)
 get last element for an HCTL
snd_hctl_elem_tsnd_hctl_find_elem (snd_hctl_t *hctl, const snd_ctl_elem_id_t *id)
 Search an HCTL element.
void snd_hctl_set_callback (snd_hctl_t *hctl, snd_hctl_callback_t callback)
 Set callback function for an HCTL.
void snd_hctl_set_callback_private (snd_hctl_t *hctl, void *data)
 Set callback private value for an HCTL.
void * snd_hctl_get_callback_private (snd_hctl_t *hctl)
 Get callback private value for an HCTL.
int snd_hctl_load (snd_hctl_t *hctl)
 Load an HCTL with all elements and sort them.
int snd_hctl_free (snd_hctl_t *hctl)
 free HCTL loaded elements
int snd_hctl_handle_events (snd_hctl_t *hctl)
 Handle pending HCTL events invoking callbacks.
const char * snd_hctl_name (snd_hctl_t *hctl)
 get identifier of HCTL handle
int snd_hctl_wait (snd_hctl_t *hctl, int timeout)
 Wait for a HCTL to become ready (i.e. at least one event pending)
snd_ctl_tsnd_hctl_ctl (snd_hctl_t *hctl)
 Get a ctl handle associated to the given hctl handle.
snd_hctl_elem_tsnd_hctl_elem_next (snd_hctl_elem_t *elem)
 get next HCTL element
snd_hctl_elem_tsnd_hctl_elem_prev (snd_hctl_elem_t *elem)
 get previous HCTL element
int snd_hctl_elem_info (snd_hctl_elem_t *elem, snd_ctl_elem_info_t *info)
 Get information for an HCTL element.
int snd_hctl_elem_read (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
 Get value for an HCTL element.
int snd_hctl_elem_write (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
 Set value for an HCTL element.
int snd_hctl_elem_tlv_read (snd_hctl_elem_t *elem, unsigned int *tlv, unsigned int tlv_size)
 Get TLV value for an HCTL element.
int snd_hctl_elem_tlv_write (snd_hctl_elem_t *elem, const unsigned int *tlv)
 Set TLV value for an HCTL element.
int snd_hctl_elem_tlv_command (snd_hctl_elem_t *elem, const unsigned int *tlv)
 Set TLV value for an HCTL element.
snd_hctl_tsnd_hctl_elem_get_hctl (snd_hctl_elem_t *elem)
 Get HCTL handle for an HCTL element.
void snd_hctl_elem_get_id (const snd_hctl_elem_t *obj, snd_ctl_elem_id_t *ptr)
 Get CTL element identifier of a CTL element id/value.
unsigned int snd_hctl_elem_get_numid (const snd_hctl_elem_t *obj)
 Get element numeric identifier of a CTL element id/value.
snd_ctl_elem_iface_t snd_hctl_elem_get_interface (const snd_hctl_elem_t *obj)
 Get interface part of CTL element identifier of a CTL element id/value.
unsigned int snd_hctl_elem_get_device (const snd_hctl_elem_t *obj)
 Get device part of CTL element identifier of a CTL element id/value.
unsigned int snd_hctl_elem_get_subdevice (const snd_hctl_elem_t *obj)
 Get subdevice part of CTL element identifier of a CTL element id/value.
const char * snd_hctl_elem_get_name (const snd_hctl_elem_t *obj)
 Get name part of CTL element identifier of a CTL element id/value.
unsigned int snd_hctl_elem_get_index (const snd_hctl_elem_t *obj)
 Get index part of CTL element identifier of a CTL element id/value.
void snd_hctl_elem_set_callback (snd_hctl_elem_t *obj, snd_hctl_elem_callback_t val)
 Set callback function for an HCTL element.
void * snd_hctl_elem_get_callback_private (const snd_hctl_elem_t *obj)
 Get callback private value for an HCTL element.
void snd_hctl_elem_set_callback_private (snd_hctl_elem_t *obj, void *val)
 Set callback private value for an HCTL element.

Detailed Description

The high level control interface. See High level control interface page for more details.


Typedef Documentation

typedef int(* snd_hctl_callback_t)(snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem)

HCTL callback function.

Parameters:
hctlHCTL handle
maskevent mask
elemrelated HCTL element (if any)
Returns:
0 on success otherwise a negative error code
typedef int(* snd_hctl_compare_t)(const snd_hctl_elem_t *e1, const snd_hctl_elem_t *e2)

Compare function for sorting HCTL elements.

Parameters:
e1First element
e2Second element
Returns:
-1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2
typedef int(* snd_hctl_elem_callback_t)(snd_hctl_elem_t *elem, unsigned int mask)

HCTL element callback function.

Parameters:
elemHCTL element
maskevent mask
Returns:
0 on success otherwise a negative error code
typedef struct _snd_hctl_elem snd_hctl_elem_t

HCTL element handle

typedef struct _snd_hctl snd_hctl_t

HCTL handle


Function Documentation

int snd_hctl_close ( snd_hctl_t hctl)

close HCTL handle

Parameters:
hctlHCTL handle
Returns:
0 on success otherwise a negative error code

Closes the specified HCTL handle and frees all associated resources.

int snd_hctl_compare_fast ( const snd_hctl_elem_t c1,
const snd_hctl_elem_t c2 
)

A "don't care" fast compare functions that may be used with snd_hctl_set_compare.

Parameters:
c1First HCTL element
c2Second HCTL element
Returns:
-1 if c1 < c2, 0 if c1 == c2, 1 if c1 > c2
snd_ctl_t* snd_hctl_ctl ( snd_hctl_t hctl)

Get a ctl handle associated to the given hctl handle.

Parameters:
hctlHCTL handle
Returns:
a ctl handle otherwise NULL
void* snd_hctl_elem_get_callback_private ( const snd_hctl_elem_t obj)

Get callback private value for an HCTL element.

Parameters:
objHCTL element
Returns:
callback private value
unsigned int snd_hctl_elem_get_device ( const snd_hctl_elem_t obj)

Get device part of CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
device part of element identifier
snd_hctl_t* snd_hctl_elem_get_hctl ( snd_hctl_elem_t elem)

Get HCTL handle for an HCTL element.

Parameters:
elemHCTL element
Returns:
HCTL handle
void snd_hctl_elem_get_id ( const snd_hctl_elem_t obj,
snd_ctl_elem_id_t ptr 
)

Get CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
ptrPointer to returned CTL element identifier
unsigned int snd_hctl_elem_get_index ( const snd_hctl_elem_t obj)

Get index part of CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
index part of element identifier
snd_ctl_elem_iface_t snd_hctl_elem_get_interface ( const snd_hctl_elem_t obj)

Get interface part of CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
interface part of element identifier
const char* snd_hctl_elem_get_name ( const snd_hctl_elem_t obj)

Get name part of CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
name part of element identifier
unsigned int snd_hctl_elem_get_numid ( const snd_hctl_elem_t obj)

Get element numeric identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
element numeric identifier
unsigned int snd_hctl_elem_get_subdevice ( const snd_hctl_elem_t obj)

Get subdevice part of CTL element identifier of a CTL element id/value.

Parameters:
objCTL element id/value
Returns:
subdevice part of element identifier
int snd_hctl_elem_info ( snd_hctl_elem_t elem,
snd_ctl_elem_info_t info 
)

Get information for an HCTL element.

Parameters:
elemHCTL element
infoHCTL element information
Returns:
0 otherwise a negative error code on failure
snd_hctl_elem_t* snd_hctl_elem_next ( snd_hctl_elem_t elem)

get next HCTL element

Parameters:
elemHCTL element
Returns:
pointer to next element
snd_hctl_elem_t* snd_hctl_elem_prev ( snd_hctl_elem_t elem)

get previous HCTL element

Parameters:
elemHCTL element
Returns:
pointer to previous element
int snd_hctl_elem_read ( snd_hctl_elem_t elem,
snd_ctl_elem_value_t value 
)

Get value for an HCTL element.

Parameters:
elemHCTL element
valueHCTL element value
Returns:
0 otherwise a negative error code on failure
void snd_hctl_elem_set_callback ( snd_hctl_elem_t obj,
snd_hctl_elem_callback_t  val 
)

Set callback function for an HCTL element.

Parameters:
objHCTL element
valcallback function
void snd_hctl_elem_set_callback_private ( snd_hctl_elem_t obj,
void *  val 
)

Set callback private value for an HCTL element.

Parameters:
objHCTL element
valcallback private value
int snd_hctl_elem_tlv_command ( snd_hctl_elem_t elem,
const unsigned int *  tlv 
)

Set TLV value for an HCTL element.

Parameters:
elemHCTL element
tlvTLV array for value
Return values:
0on success
>1on success when value was changed
<0a negative error code on failure
int snd_hctl_elem_tlv_read ( snd_hctl_elem_t elem,
unsigned int *  tlv,
unsigned int  tlv_size 
)

Get TLV value for an HCTL element.

Parameters:
elemHCTL element
tlvTLV array for value
tlv_sizesize of TLV array in bytes
Returns:
0 otherwise a negative error code on failure
int snd_hctl_elem_tlv_write ( snd_hctl_elem_t elem,
const unsigned int *  tlv 
)

Set TLV value for an HCTL element.

Parameters:
elemHCTL element
tlvTLV array for value
Return values:
0on success
>1on success when value was changed
<0a negative error code on failure
int snd_hctl_elem_write ( snd_hctl_elem_t elem,
snd_ctl_elem_value_t value 
)

Set value for an HCTL element.

Parameters:
elemHCTL element
valueHCTL element value
Return values:
0on success
>1on success when value was changed
<0a negative error code on failure
snd_hctl_elem_t* snd_hctl_find_elem ( snd_hctl_t hctl,
const snd_ctl_elem_id_t id 
)

Search an HCTL element.

Parameters:
hctlHCTL handle
idElement identifier
Returns:
pointer to found HCTL element or NULL if it does not exists
snd_hctl_elem_t* snd_hctl_first_elem ( snd_hctl_t hctl)

get first element for an HCTL

Parameters:
hctlHCTL handle
Returns:
pointer to first element
int snd_hctl_free ( snd_hctl_t hctl)

free HCTL loaded elements

Parameters:
hctlHCTL handle
Returns:
0 on success otherwise a negative error code
void* snd_hctl_get_callback_private ( snd_hctl_t hctl)

Get callback private value for an HCTL.

Parameters:
hctlHCTL handle
Returns:
callback private value
unsigned int snd_hctl_get_count ( snd_hctl_t hctl)

Get number of loaded elements for an HCTL.

Parameters:
hctlHCTL handle
Returns:
elements count
int snd_hctl_handle_events ( snd_hctl_t hctl)

Handle pending HCTL events invoking callbacks.

Parameters:
hctlHCTL handle
Returns:
0 otherwise a negative error code on failure
snd_hctl_elem_t* snd_hctl_last_elem ( snd_hctl_t hctl)

get last element for an HCTL

Parameters:
hctlHCTL handle
Returns:
pointer to last element
int snd_hctl_load ( snd_hctl_t hctl)

Load an HCTL with all elements and sort them.

Parameters:
hctlHCTL handle
Returns:
0 on success otherwise a negative error code
const char* snd_hctl_name ( snd_hctl_t hctl)

get identifier of HCTL handle

Parameters:
hctlHCTL handle
Returns:
ascii identifier of HCTL handle

Returns the ASCII identifier of given HCTL handle. It's the same identifier specified in snd_hctl_open().

int snd_hctl_nonblock ( snd_hctl_t hctl,
int  nonblock 
)

set nonblock mode

Parameters:
hctlHCTL handle
nonblock0 = block, 1 = nonblock mode
Returns:
0 on success otherwise a negative error code
int snd_hctl_open ( snd_hctl_t **  hctlp,
const char *  name,
int  mode 
)

Opens an HCTL.

Parameters:
hctlpReturned HCTL handle
nameASCII identifier of the underlying CTL handle
modeOpen mode (see SND_CTL_NONBLOCK, SND_CTL_ASYNC)
Returns:
0 on success otherwise a negative error code
int snd_hctl_open_ctl ( snd_hctl_t **  hctlp,
snd_ctl_t ctl 
)

Opens an HCTL.

Parameters:
hctlpReturned HCTL handle
ctlunderlying CTL handle
Returns:
0 on success otherwise a negative error code
int snd_hctl_poll_descriptors ( snd_hctl_t hctl,
struct pollfd *  pfds,
unsigned int  space 
)

get poll descriptors

Parameters:
hctlHCTL handle
pfdsarray of poll descriptors
spacespace in the poll descriptor array
Returns:
count of filled descriptors
int snd_hctl_poll_descriptors_count ( snd_hctl_t hctl)

get count of poll descriptors for HCTL handle

Parameters:
hctlHCTL handle
Returns:
count of poll descriptors
int snd_hctl_poll_descriptors_revents ( snd_hctl_t hctl,
struct pollfd *  pfds,
unsigned int  nfds,
unsigned short *  revents 
)

get returned events from poll descriptors

Parameters:
hctlHCTL handle
pfdsarray of poll descriptors
nfdscount of poll descriptors
reventsreturned events
Returns:
zero if success, otherwise a negative error code
void snd_hctl_set_callback ( snd_hctl_t hctl,
snd_hctl_callback_t  callback 
)

Set callback function for an HCTL.

Parameters:
hctlHCTL handle
callbackcallback function
void snd_hctl_set_callback_private ( snd_hctl_t hctl,
void *  callback_private 
)

Set callback private value for an HCTL.

Parameters:
hctlHCTL handle
callback_privatecallback private value
int snd_hctl_set_compare ( snd_hctl_t hctl,
snd_hctl_compare_t  compare 
)

Change HCTL compare function and reorder elements.

Parameters:
hctlHCTL handle
compareElement compare function
Returns:
0 on success otherwise a negative error code
int snd_hctl_wait ( snd_hctl_t hctl,
int  timeout 
)

Wait for a HCTL to become ready (i.e. at least one event pending)

Parameters:
hctlHCTL handle
timeoutmaximum time in milliseconds to wait
Returns:
a positive value on success otherwise a negative error code
Return values:
0timeout occurred
1an event is pending