ALSA project - the C library reference

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. More...
typedef int(* | snd_hctl_callback_t) (snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem)
| HCTL callback function. More...
typedef int(* | snd_hctl_elem_callback_t) (snd_hctl_elem_t *elem, unsigned int mask)
| HCTL element callback function. More...

## 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. More...
int | snd_hctl_open (snd_hctl_t **hctl, const char *name, int mode)
| Opens an HCTL. More...
int | snd_hctl_open_ctl (snd_hctl_t **hctlp, snd_ctl_t *ctl)
| Opens an HCTL. More...
int | snd_hctl_close (snd_hctl_t *hctl)
| close HCTL handle More...
int | snd_hctl_nonblock (snd_hctl_t *hctl, int nonblock)
| set nonblock mode More...
int | snd_hctl_poll_descriptors_count (snd_hctl_t *hctl)
| get count of poll descriptors for HCTL handle More...
int | snd_hctl_poll_descriptors (snd_hctl_t *hctl, struct pollfd *pfds, unsigned int space)
| get poll descriptors More...
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 More...
unsigned int | snd_hctl_get_count (snd_hctl_t *hctl)
| Get number of loaded elements for an HCTL. More...
int | snd_hctl_set_compare (snd_hctl_t *hctl, snd_hctl_compare_t hsort)
| Change HCTL compare function and reorder elements. More...
snd_hctl_elem_t * | snd_hctl_first_elem (snd_hctl_t *hctl)
| get first element for an HCTL More...
snd_hctl_elem_t * | snd_hctl_last_elem (snd_hctl_t *hctl)
| get last element for an HCTL More...
snd_hctl_elem_t * | snd_hctl_find_elem (snd_hctl_t *hctl, const snd_ctl_elem_id_t *id)
| Search an HCTL element. More...
void | snd_hctl_set_callback (snd_hctl_t *hctl, snd_hctl_callback_t callback)
| Set callback function for an HCTL. More...
void | snd_hctl_set_callback_private (snd_hctl_t *hctl, void *data)
| Set callback private value for an HCTL. More...
void * | snd_hctl_get_callback_private (snd_hctl_t *hctl)
| Get callback private value for an HCTL. More...
int | snd_hctl_load (snd_hctl_t *hctl)
| Load an HCTL with all elements and sort them. More...
int | snd_hctl_free (snd_hctl_t *hctl)
| free HCTL loaded elements More...
int | snd_hctl_handle_events (snd_hctl_t *hctl)
| Handle pending HCTL events invoking callbacks. More...
const char * | snd_hctl_name (snd_hctl_t *hctl)
| get identifier of HCTL handle More...
int | snd_hctl_wait (snd_hctl_t *hctl, int timeout)
| Wait for a HCTL to become ready (i.e. at least one event pending) More...
snd_ctl_t * | snd_hctl_ctl (snd_hctl_t *hctl)
| Get a ctl handle associated to the given hctl handle. More...
snd_hctl_elem_t * | snd_hctl_elem_next (snd_hctl_elem_t *elem)
| get next HCTL element More...
snd_hctl_elem_t * | snd_hctl_elem_prev (snd_hctl_elem_t *elem)
| get previous HCTL element More...
int | snd_hctl_elem_info (snd_hctl_elem_t *elem, snd_ctl_elem_info_t *info)
| Get information for an HCTL element. More...
int | snd_hctl_elem_read (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
| Get value for an HCTL element. More...
int | snd_hctl_elem_write (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
| Set value for an HCTL element. More...
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. More...
int | snd_hctl_elem_tlv_write (snd_hctl_elem_t *elem, const unsigned int *tlv)
| Set TLV value for an HCTL element. More...
int | snd_hctl_elem_tlv_command (snd_hctl_elem_t *elem, const unsigned int *tlv)
| Set TLV value for an HCTL element. More...
snd_hctl_t * | snd_hctl_elem_get_hctl (snd_hctl_elem_t *elem)
| Get HCTL handle for an HCTL element. More...
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. More...
unsigned int | snd_hctl_elem_get_numid (const snd_hctl_elem_t *obj)
| Get element numeric identifier of a CTL element id/value. More...
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. More...
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. More...
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. More...
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. More...
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. More...
void | snd_hctl_elem_set_callback (snd_hctl_elem_t *obj, snd_hctl_elem_callback_t val)
| Set callback function for an HCTL element. More...
void * | snd_hctl_elem_get_callback_private (const snd_hctl_elem_t *obj)
| Get callback private value for an HCTL element. More...
void | snd_hctl_elem_set_callback_private (snd_hctl_elem_t *obj, void *val)
| Set callback private value for an HCTL element. More...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  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

## ◆ 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

  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

## ◆ 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

  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

## ◆ 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

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

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

  hctl | HCTL handle

Returns
  pointer to first element

## ◆ snd_hctl_free()

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

## ◆ snd_hctl_get_callback_private()

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

## ◆ snd_hctl_get_count()

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

## ◆ snd_hctl_handle_events()

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

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

## ◆ snd_hctl_load()

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

## ◆ snd_hctl_name()

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

## ◆ snd_hctl_nonblock()

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

## ◆ snd_hctl_open()

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

## ◆ snd_hctl_open_ctl()

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

## ◆ snd_hctl_poll_descriptors()

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

## ◆ snd_hctl_poll_descriptors_count()

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

## ◆ 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

  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

## ◆ 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

  hctl | HCTL handle
  callback | callback 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

  hctl | HCTL handle
  callback_private | callback 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

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

  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