ALSA project - the C library reference
 
Loading...
Searching...
No Matches
High level 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

◆ snd_hctl_callback_t

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

◆ snd_hctl_compare_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.

Parameters
e1First element
e2Second element
Returns
-1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2

◆ snd_hctl_elem_callback_t

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

◆ snd_hctl_elem_t

typedef struct _snd_hctl_elem snd_hctl_elem_t

HCTL element handle

◆ snd_hctl_t

typedef struct _snd_hctl snd_hctl_t

HCTL handle

Function Documentation

◆ snd_hctl_close()

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.

◆ snd_hctl_compare_fast()

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_hctl_ctl()

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

◆ snd_hctl_elem_get_callback_private()

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

◆ snd_hctl_elem_get_device()

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_elem_get_hctl()

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

◆ snd_hctl_elem_get_id()

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

◆ snd_hctl_elem_get_index()

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_hctl_elem_get_interface()

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

◆ snd_hctl_elem_get_name()

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

◆ snd_hctl_elem_get_numid()

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

◆ snd_hctl_elem_get_subdevice()

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

◆ snd_hctl_elem_info()

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_next()

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_prev()

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

◆ snd_hctl_elem_read()

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

◆ snd_hctl_elem_set_callback()

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

◆ snd_hctl_elem_set_callback_private()

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

◆ snd_hctl_elem_tlv_command()

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

◆ snd_hctl_elem_tlv_read()

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

◆ snd_hctl_elem_tlv_write()

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

◆ snd_hctl_elem_write()

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_find_elem()

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_first_elem()

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

◆ snd_hctl_free()

int snd_hctl_free ( snd_hctl_t * hctl)

free HCTL loaded elements

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

◆ snd_hctl_get_callback_private()

void * snd_hctl_get_callback_private ( snd_hctl_t * hctl)

Get callback private value for an HCTL.

Parameters
hctlHCTL handle
Returns
callback private value

◆ snd_hctl_get_count()

unsigned int snd_hctl_get_count ( snd_hctl_t * hctl)

Get number of loaded elements for an HCTL.

Parameters
hctlHCTL handle
Returns
elements count

◆ snd_hctl_handle_events()

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_last_elem()

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

◆ snd_hctl_load()

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

◆ snd_hctl_name()

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

◆ snd_hctl_nonblock()

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

◆ snd_hctl_open()

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

◆ snd_hctl_open_ctl()

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

◆ snd_hctl_poll_descriptors()

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

◆ snd_hctl_poll_descriptors_count()

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

◆ snd_hctl_poll_descriptors_revents()

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

◆ snd_hctl_set_callback()

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

◆ snd_hctl_set_callback_private()

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

◆ snd_hctl_set_compare()

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

◆ snd_hctl_wait()

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