ALSA project - the C library reference: High level Control Interface

# 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_t * | snd_hctl_first_elem (snd_hctl_t *hctl)
| get first element for an HCTL
snd_hctl_elem_t * | snd_hctl_last_elem (snd_hctl_t *hctl)
| get last element for an HCTL
snd_hctl_elem_t * | snd_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_t * | snd_hctl_ctl (snd_hctl_t *hctl)
| Get a ctl handle associated to the given hctl handle.
snd_hctl_elem_t * | snd_hctl_elem_next (snd_hctl_elem_t *elem)
| get next HCTL element
snd_hctl_elem_t * | snd_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_t * | snd_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:

  | hctl | HCTL handle
  | mask | event mask
  | elem | related 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:

  | e1 | First element
  | e2 | Second 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:

  | elem | HCTL element
  | mask | event 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:

  | hctl | HCTL 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:

  | c1 | First HCTL element
  | c2 | Second 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:

  | hctl | HCTL 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:

  | obj | HCTL 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:

  | obj | CTL 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:

  | elem | HCTL 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:

  | obj | CTL element id/value
  | ptr | Pointer 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:

  | obj | CTL 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:

  | obj | CTL 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:

  | obj | CTL 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:

  | obj | CTL 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:

  | obj | CTL 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:

  | elem | HCTL element
  | info | HCTL 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:

  | elem | HCTL element

Returns:
  pointer to next element

snd_hctl_elem_t* snd_hctl_elem_prev | ( | snd_hctl_elem_t * | elem | ) |

get previous HCTL element

Parameters:

  | elem | HCTL 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:

  | elem | HCTL element
  | value | HCTL 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:

  | obj | HCTL element
  | val | callback function

void snd_hctl_elem_set_callback_private | ( | snd_hctl_elem_t * | obj,
|  | void * | val |
| ) |  |  |

Set callback private value for an HCTL element.

Parameters:

  | obj | HCTL element
  | val | callback 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:

  | elem | HCTL element
  | tlv | TLV array for value

Return values:

  | 0 | on success
  | >1 | on success when value was changed
  | <0 | a 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:

  | elem | HCTL element
  | tlv | TLV array for value
  | tlv_size | size 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:

  | elem | HCTL element
  | tlv | TLV array for value

Return values:

  | 0 | on success
  | >1 | on success when value was changed
  | <0 | a 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:

  | elem | HCTL element
  | value | HCTL element value

Return values:

  | 0 | on success
  | >1 | on success when value was changed
  | <0 | a 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:

  | hctl | HCTL handle
  | id | Element 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:

  | hctl | HCTL handle

Returns:
  pointer to first element

int snd_hctl_free | ( | snd_hctl_t * | hctl | ) |

free HCTL loaded elements

Parameters:

  | hctl | HCTL 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:

  | hctl | HCTL handle

Returns:
  callback private value

unsigned int snd_hctl_get_count | ( | snd_hctl_t * | hctl | ) |

Get number of loaded elements for an HCTL.

Parameters:

  | hctl | HCTL handle

Returns:
  elements count

int snd_hctl_handle_events | ( | snd_hctl_t * | hctl | ) |

Handle pending HCTL events invoking callbacks.

Parameters:

  | hctl | HCTL 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:

  | hctl | HCTL handle

Returns:
  pointer to last element

int snd_hctl_load | ( | snd_hctl_t * | hctl | ) |

Load an HCTL with all elements and sort them.

Parameters:

  | hctl | HCTL 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:

  | hctl | HCTL 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:

  | hctl | HCTL handle
  | nonblock | 0 = 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:

  | hctlp | Returned HCTL handle
  | name | ASCII identifier of the underlying CTL handle
  | mode | Open 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:

  | hctlp | Returned HCTL handle
  | ctl | underlying 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:

  | hctl | HCTL handle
  | pfds | array of poll descriptors
  | space | space 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:

  | hctl | HCTL 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:

  | hctl | HCTL handle
  | pfds | array of poll descriptors
  | nfds | count of poll descriptors
  | revents | returned 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:

  | hctl | HCTL handle
  | callback | callback function

void snd_hctl_set_callback_private | ( | snd_hctl_t * | hctl,
|  | void * | callback_private |
| ) |  |  |

Set callback private value for an HCTL.

Parameters:

  | hctl | HCTL handle
  | callback_private | callback private value

int snd_hctl_set_compare | ( | snd_hctl_t * | hctl,
|  | snd_hctl_compare_t | compare |
| ) |  |  |

Change HCTL compare function and reorder elements.

Parameters:

  | hctl | HCTL handle
  | compare | Element 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:

  | hctl | HCTL handle
  | timeout | maximum time in milliseconds to wait

Returns:
  a positive value on success otherwise a negative error code

Return values:

  | 0 | timeout occurred
  | 1 | an event is pending

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines