ALSA project - the C library reference: Mixer Interface

ALSA project - the C library reference

- Main Page
- Related Pages
- Modules
- Data Structures
- Files
- Examples

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Modules | Macros | Typedefs | Enumerations | Functions
Mixer Interface

## Modules
| Simple Mixer Interface

## Macros
#define | snd_mixer_class_alloca(ptr)
| allocate an invalid snd_mixer_class_t using standard alloca More...

## Typedefs
typedef struct _snd_mixer | snd_mixer_t
typedef struct _snd_mixer_class | snd_mixer_class_t
typedef struct _snd_mixer_elem | snd_mixer_elem_t
typedef int(* | snd_mixer_callback_t )(snd_mixer_t *ctl, unsigned int mask, snd_mixer_elem_t *elem)
| Mixer callback function. More...
typedef int(* | snd_mixer_elem_callback_t )(snd_mixer_elem_t *elem, unsigned int mask)
| Mixer element callback function. More...
typedef int(* | snd_mixer_compare_t )(const snd_mixer_elem_t *e1, const snd_mixer_elem_t *e2)
| Compare function for sorting mixer elements. More...
typedef int(* | snd_mixer_event_t )(snd_mixer_class_t *class_, unsigned int mask, snd_hctl_elem_t *helem, snd_mixer_elem_t *melem)
| Event callback for the mixer class. More...

## Enumerations
enum | snd_mixer_elem_type_t { SND_MIXER_ELEM_SIMPLE, SND_MIXER_ELEM_LAST = SND_MIXER_ELEM_SIMPLE }

## Functions
int | snd_mixer_open (snd_mixer_t **mixer, int mode)
| Opens an empty mixer. More...
int | snd_mixer_close (snd_mixer_t *mixer)
| Close a mixer and free all related resources. More...
snd_mixer_elem_t * | snd_mixer_first_elem (snd_mixer_t *mixer)
| get first element for a mixer More...
snd_mixer_elem_t * | snd_mixer_last_elem (snd_mixer_t *mixer)
| get last element for a mixer More...
int | snd_mixer_handle_events (snd_mixer_t *mixer)
| Handle pending mixer events invoking callbacks. More...
int | snd_mixer_attach (snd_mixer_t *mixer, const char *name)
| Attach an HCTL specified with the CTL device name to an opened mixer. More...
int | snd_mixer_attach_hctl (snd_mixer_t *mixer, snd_hctl_t *hctl)
| Attach an HCTL to an opened mixer. More...
int | snd_mixer_detach (snd_mixer_t *mixer, const char *name)
| Detach a previously attached HCTL to an opened mixer freeing all related resources. More...
int | snd_mixer_detach_hctl (snd_mixer_t *mixer, snd_hctl_t *hctl)
| Detach a previously attached HCTL to an opened mixer freeing all related resources. More...
int | snd_mixer_get_hctl (snd_mixer_t *mixer, const char *name, snd_hctl_t **hctl)
| Obtain a HCTL pointer associated to given name. More...
int | snd_mixer_poll_descriptors_count (snd_mixer_t *mixer)
| get count of poll descriptors for mixer handle More...
int | snd_mixer_poll_descriptors (snd_mixer_t *mixer, struct pollfd *pfds, unsigned int space)
| get poll descriptors More...
int | snd_mixer_poll_descriptors_revents (snd_mixer_t *mixer, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
| get returned events from poll descriptors More...
int | snd_mixer_load (snd_mixer_t *mixer)
| Load a mixer elements. More...
void | snd_mixer_free (snd_mixer_t *mixer)
| Unload all mixer elements and free all related resources. More...
int | snd_mixer_wait (snd_mixer_t *mixer, int timeout)
| Wait for a mixer to become ready (i.e. at least one event pending) More...
int | snd_mixer_set_compare (snd_mixer_t *mixer, snd_mixer_compare_t msort)
| Change mixer compare function and reorder elements. More...
void | snd_mixer_set_callback (snd_mixer_t *obj, snd_mixer_callback_t val)
| Set callback function for a mixer. More...
void * | snd_mixer_get_callback_private (const snd_mixer_t *obj)
| Get callback private value for a mixer. More...
void | snd_mixer_set_callback_private (snd_mixer_t *obj, void *val)
| Set callback private value for a mixer. More...
unsigned int | snd_mixer_get_count (const snd_mixer_t *obj)
| Get elements count for a mixer. More...
int | snd_mixer_class_unregister (snd_mixer_class_t *clss)
| Unregister mixer element class and remove all its elements. More...
snd_mixer_elem_t * | snd_mixer_elem_next (snd_mixer_elem_t *elem)
| get next mixer element More...
snd_mixer_elem_t * | snd_mixer_elem_prev (snd_mixer_elem_t *elem)
| get previous mixer element More...
void | snd_mixer_elem_set_callback (snd_mixer_elem_t *obj, snd_mixer_elem_callback_t val)
| Set callback function for a mixer element. More...
void * | snd_mixer_elem_get_callback_private (const snd_mixer_elem_t *obj)
| Get callback private value for a mixer element. More...
void | snd_mixer_elem_set_callback_private (snd_mixer_elem_t *obj, void *val)
| Set callback private value for a mixer element. More...
snd_mixer_elem_type_t | snd_mixer_elem_get_type (const snd_mixer_elem_t *obj)
| Get type for a mixer element. More...
int | snd_mixer_class_register (snd_mixer_class_t *class_, snd_mixer_t *mixer)
| Register mixer element class. More...
int | snd_mixer_elem_new (snd_mixer_elem_t **elem, snd_mixer_elem_type_t type, int compare_weight, void *private_data, void(*private_free)(snd_mixer_elem_t *elem))
| Allocate a new mixer element. More...
int | snd_mixer_elem_add (snd_mixer_elem_t *elem, snd_mixer_class_t *class_)
| Add an element for a registered mixer element class. More...
int | snd_mixer_elem_remove (snd_mixer_elem_t *elem)
| Remove a mixer element. More...
void | snd_mixer_elem_free (snd_mixer_elem_t *elem)
| Free a mixer element. More...
int | snd_mixer_elem_info (snd_mixer_elem_t *elem)
| Mixer element informations are changed. More...
int | snd_mixer_elem_value (snd_mixer_elem_t *elem)
| Mixer element values is changed. More...
int | snd_mixer_elem_attach (snd_mixer_elem_t *melem, snd_hctl_elem_t *helem)
| Attach an HCTL element to a mixer element. More...
int | snd_mixer_elem_detach (snd_mixer_elem_t *melem, snd_hctl_elem_t *helem)
| Detach an HCTL element from a mixer element. More...
int | snd_mixer_elem_empty (snd_mixer_elem_t *melem)
| Return true if a mixer element does not contain any HCTL elements. More...
void * | snd_mixer_elem_get_private (const snd_mixer_elem_t *melem)
| Get private data associated to give mixer element. More...
size_t | snd_mixer_class_sizeof (void)
| get size of snd_mixer_class_t More...
int | snd_mixer_class_malloc (snd_mixer_class_t **ptr)
| allocate an invalid snd_mixer_class_t using standard malloc More...
void | snd_mixer_class_free (snd_mixer_class_t *obj)
| frees a previously allocated snd_mixer_class_t More...
void | snd_mixer_class_copy (snd_mixer_class_t *dst, const snd_mixer_class_t *src)
| copy one snd_mixer_class_t to another More...
snd_mixer_t * | snd_mixer_class_get_mixer (const snd_mixer_class_t *class_)
| Get a mixer associated to given mixer class. More...
snd_mixer_event_t | snd_mixer_class_get_event (const snd_mixer_class_t *class_)
| Get mixer event callback associated to given mixer class. More...
void * | snd_mixer_class_get_private (const snd_mixer_class_t *class_)
| Get mixer private data associated to given mixer class. More...
snd_mixer_compare_t | snd_mixer_class_get_compare (const snd_mixer_class_t *class_)
| Get mixer compare callback associated to given mixer class. More...
int | snd_mixer_class_set_event (snd_mixer_class_t *class_, snd_mixer_event_t event)
| Set mixer event callback to given mixer class. More...
int | snd_mixer_class_set_private (snd_mixer_class_t *class_, void *private_data)
| Set mixer private data to given mixer class. More...
int | snd_mixer_class_set_private_free (snd_mixer_class_t *class_, void(*private_free)(snd_mixer_class_t *))
| Set mixer private data free callback to given mixer class. More...
int | snd_mixer_class_set_compare (snd_mixer_class_t *class_, snd_mixer_compare_t compare)
| Set mixer compare callback to given mixer class. More...

## Detailed Description

The mixer interface.

## Macro Definition Documentation

#define snd_mixer_class_alloca | ( |  | ptr | ) |

allocate an invalid snd_mixer_class_t using standard alloca

Parameters

  ptr | returned pointer

## Typedef Documentation

typedef int(* snd_mixer_callback_t)(snd_mixer_t *ctl, unsigned int mask, snd_mixer_elem_t *elem)

Mixer callback function.

Parameters

  mixer | Mixer handle
  mask | event mask
  elem | related mixer element (if any)

Returns
  0 on success otherwise a negative error code

typedef struct _snd_mixer_class snd_mixer_class_t

Mixer elements class handle

typedef int(* snd_mixer_compare_t)(const snd_mixer_elem_t *e1, const snd_mixer_elem_t *e2)

Compare function for sorting mixer elements.

Parameters

  e1 | First element
  e2 | Second element

Returns
  -1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2

typedef int(* snd_mixer_elem_callback_t)(snd_mixer_elem_t *elem, unsigned int mask)

Mixer element callback function.

Parameters

  elem | Mixer element
  mask | event mask

Returns
  0 on success otherwise a negative error code

typedef struct _snd_mixer_elem snd_mixer_elem_t

Mixer element handle

typedef int(* snd_mixer_event_t)(snd_mixer_class_t *class_, unsigned int mask, snd_hctl_elem_t *helem, snd_mixer_elem_t *melem)

Event callback for the mixer class.

Parameters

  class_ | Mixer class
  mask | Event mask (SND_CTL_EVENT_*)
  helem | HCTL element which invoked the event
  melem | Mixer element associated to HCTL element

Returns
  zero if success, otherwise a negative error value

typedef struct _snd_mixer snd_mixer_t

Mixer handle

## Enumeration Type Documentation

enum snd_mixer_elem_type_t

Mixer element type

## Function Documentation

int snd_mixer_attach | ( | snd_mixer_t * | mixer,
|  | const char * | name
| ) |  |

Attach an HCTL specified with the CTL device name to an opened mixer.

Parameters

  mixer | Mixer handle
  name | HCTL name (see snd_hctl_open)

Returns
  0 on success otherwise a negative error code

int snd_mixer_attach_hctl | ( | snd_mixer_t * | mixer,
|  | snd_hctl_t * | hctl
| ) |  |

Attach an HCTL to an opened mixer.

Parameters

  mixer | Mixer handle
  hctl | the HCTL to be attached

Returns
  0 on success otherwise a negative error code

Upon error, this function closes the given hctl handle automatically.

void snd_mixer_class_copy | ( | snd_mixer_class_t * | dst,
|  | const snd_mixer_class_t * | src
| ) |  |

copy one snd_mixer_class_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

void snd_mixer_class_free | ( | snd_mixer_class_t * | obj | ) |

frees a previously allocated snd_mixer_class_t

Parameters

  obj | pointer to object to free

snd_mixer_compare_t snd_mixer_class_get_compare | ( | const snd_mixer_class_t * | obj | ) |

Get mixer compare callback associated to given mixer class.

Parameters

  obj | Mixer simple class identifier

Returns
  event callback pointer

snd_mixer_event_t snd_mixer_class_get_event | ( | const snd_mixer_class_t * | obj | ) |

Get mixer event callback associated to given mixer class.

Parameters

  obj | Mixer simple class identifier

Returns
  event callback pointer

snd_mixer_t* snd_mixer_class_get_mixer | ( | const snd_mixer_class_t * | obj | ) |

Get a mixer associated to given mixer class.

Parameters

  obj | Mixer simple class identifier

Returns
  mixer pointer

void* snd_mixer_class_get_private | ( | const snd_mixer_class_t * | obj | ) |

Get mixer private data associated to given mixer class.

Parameters

  obj | Mixer simple class identifier

Returns
  event callback pointer

int snd_mixer_class_malloc | ( | snd_mixer_class_t ** | ptr | ) |

allocate an invalid snd_mixer_class_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

int snd_mixer_class_register | ( | snd_mixer_class_t * | class,
|  | snd_mixer_t * | mixer
| ) |  |

Register mixer element class.

Parameters

  class | Mixer element class
  mixer | Mixer handle

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

int snd_mixer_class_set_compare | ( | snd_mixer_class_t * | obj,
|  | snd_mixer_compare_t | compare
| ) |  |

Set mixer compare callback to given mixer class.

Parameters

  obj | Mixer simple class identifier
  compare | the compare callback to be used

Returns
  zero if success, otherwise a negative error code

int snd_mixer_class_set_event | ( | snd_mixer_class_t * | obj,
|  | snd_mixer_event_t | event
| ) |  |

Set mixer event callback to given mixer class.

Parameters

  obj | Mixer simple class identifier
  event | Event callback

Returns
  zero if success, otherwise a negative error code

int snd_mixer_class_set_private | ( | snd_mixer_class_t * | obj,
|  | void * | private_data
| ) |  |

Set mixer private data to given mixer class.

Parameters

  obj | Mixer simple class identifier
  private_data | class private data

Returns
  zero if success, otherwise a negative error code

int snd_mixer_class_set_private_free | ( | snd_mixer_class_t * | obj,
|  | void(*)(snd_mixer_class_t *) | private_free
| ) |  |

Set mixer private data free callback to given mixer class.

Parameters

  obj | Mixer simple class identifier
  private_free | Mixer class private data free callback

Returns
  zero if success, otherwise a negative error code

size_t snd_mixer_class_sizeof | ( | void |  | ) |

get size of snd_mixer_class_t

Returns
  size in bytes

int snd_mixer_class_unregister | ( | snd_mixer_class_t * | class | ) |

Unregister mixer element class and remove all its elements.

Parameters

  class | Mixer element class

Returns
  0 on success otherwise a negative error code

Note that the class structure is also deallocated!

int snd_mixer_close | ( | snd_mixer_t * | mixer | ) |

Close a mixer and free all related resources.

Parameters

  mixer | Mixer handle

Returns
  0 on success otherwise a negative error code

int snd_mixer_detach | ( | snd_mixer_t * | mixer,
|  | const char * | name
| ) |  |

Detach a previously attached HCTL to an opened mixer freeing all related resources.

Parameters

  mixer | Mixer handle
  name | HCTL previously attached

Returns
  0 on success otherwise a negative error code

int snd_mixer_detach_hctl | ( | snd_mixer_t * | mixer,
|  | snd_hctl_t * | hctl
| ) |  |

Detach a previously attached HCTL to an opened mixer freeing all related resources.

Parameters

  mixer | Mixer handle
  hctl | HCTL previously attached

Returns
  0 on success otherwise a negative error code

Note: The hctl handle is not closed!

int snd_mixer_elem_add | ( | snd_mixer_elem_t * | elem,
|  | snd_mixer_class_t * | class
| ) |  |

Add an element for a registered mixer element class.

Parameters

  elem | Mixer element
  class | Mixer element class

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

int snd_mixer_elem_attach | ( | snd_mixer_elem_t * | melem,
|  | snd_hctl_elem_t * | helem
| ) |  |

Attach an HCTL element to a mixer element.

Parameters

  melem | Mixer element
  helem | HCTL element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

int snd_mixer_elem_detach | ( | snd_mixer_elem_t * | melem,
|  | snd_hctl_elem_t * | helem
| ) |  |

Detach an HCTL element from a mixer element.

Parameters

  melem | Mixer element
  helem | HCTL element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

int snd_mixer_elem_empty | ( | snd_mixer_elem_t * | melem | ) |

Return true if a mixer element does not contain any HCTL elements.

Parameters

  melem | Mixer element

Returns
  0 if not empty, 1 if empty

For use by mixer element class specific code.

void snd_mixer_elem_free | ( | snd_mixer_elem_t * | elem | ) |

Free a mixer element.

Parameters

  elem | Mixer element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

void* snd_mixer_elem_get_callback_private | ( | const snd_mixer_elem_t * | mixer | ) |

Get callback private value for a mixer element.

Parameters

  mixer | mixer element

Returns
  callback private value

void* snd_mixer_elem_get_private | ( | const snd_mixer_elem_t * | elem | ) |

Get private data associated to give mixer element.

Parameters

  elem | Mixer element

Returns
  private data

For use by mixer element class specific code.

snd_mixer_elem_type_t snd_mixer_elem_get_type | ( | const snd_mixer_elem_t * | mixer | ) |

Get type for a mixer element.

Parameters

  mixer | mixer element

Returns
  mixer element type

int snd_mixer_elem_info | ( | snd_mixer_elem_t * | elem | ) |

Mixer element informations are changed.

Parameters

  elem | Mixer element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

int snd_mixer_elem_new | ( | snd_mixer_elem_t ** | elem,
|  | snd_mixer_elem_type_t | type,
|  | int | compare_weight,
|  | void * | private_data,
|  | void(*)(snd_mixer_elem_t *elem) | private_free
| ) |  |

Allocate a new mixer element.

Parameters

  elem | Returned mixer element
  type | Mixer element type
  compare_weight | Mixer element compare weight
  private_data | Private data
  private_free | Private data free callback

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

snd_mixer_elem_t* snd_mixer_elem_next | ( | snd_mixer_elem_t * | elem | ) |

get next mixer element

Parameters

  elem | mixer element

Returns
  pointer to next element

snd_mixer_elem_t* snd_mixer_elem_prev | ( | snd_mixer_elem_t * | elem | ) |

get previous mixer element

Parameters

  elem | mixer element

Returns
  pointer to previous element

int snd_mixer_elem_remove | ( | snd_mixer_elem_t * | elem | ) |

Remove a mixer element.

Parameters

  elem | Mixer element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

void snd_mixer_elem_set_callback | ( | snd_mixer_elem_t * | mixer,
|  | snd_mixer_elem_callback_t | val
| ) |  |

Set callback function for a mixer element.

Parameters

  mixer | mixer element
  val | callback function

void snd_mixer_elem_set_callback_private | ( | snd_mixer_elem_t * | mixer,
|  | void * | val
| ) |  |

Set callback private value for a mixer element.

Parameters

  mixer | mixer element
  val | callback private value

int snd_mixer_elem_value | ( | snd_mixer_elem_t * | elem | ) |

Mixer element values is changed.

Parameters

  elem | Mixer element

Returns
  0 on success otherwise a negative error code

For use by mixer element class specific code.

snd_mixer_elem_t* snd_mixer_first_elem | ( | snd_mixer_t * | mixer | ) |

get first element for a mixer

Parameters

  mixer | Mixer handle

Returns
  pointer to first element

void snd_mixer_free | ( | snd_mixer_t * | mixer | ) |

Unload all mixer elements and free all related resources.

Parameters

  mixer | Mixer handle

void* snd_mixer_get_callback_private | ( | const snd_mixer_t * | mixer | ) |

Get callback private value for a mixer.

Parameters

  mixer | mixer handle

Returns
  callback private value

unsigned int snd_mixer_get_count | ( | const snd_mixer_t * | mixer | ) |

Get elements count for a mixer.

Parameters

  mixer | mixer handle

Returns
  elements count

int snd_mixer_get_hctl | ( | snd_mixer_t * | mixer,
|  | const char * | name,
|  | snd_hctl_t ** | hctl
| ) |  |

Obtain a HCTL pointer associated to given name.

Parameters

  mixer | Mixer handle
  name | HCTL previously attached
  hctl | HCTL pointer

Returns
  0 on success otherwise a negative error code

int snd_mixer_handle_events | ( | snd_mixer_t * | mixer | ) |

Handle pending mixer events invoking callbacks.

Parameters

  mixer | Mixer handle

Returns
  Number of events that occured on success, otherwise a negative error code on failure

snd_mixer_elem_t* snd_mixer_last_elem | ( | snd_mixer_t * | mixer | ) |

get last element for a mixer

Parameters

  mixer | Mixer handle

Returns
  pointer to last element

int snd_mixer_load | ( | snd_mixer_t * | mixer | ) |

Load a mixer elements.

Parameters

  mixer | Mixer handle

Returns
  0 on success otherwise a negative error code

int snd_mixer_open | ( | snd_mixer_t ** | mixerp,
|  | int | mode
| ) |  |

Opens an empty mixer.

Parameters

  mixerp | Returned mixer handle
  mode | Open mode

Returns
  0 on success otherwise a negative error code

int snd_mixer_poll_descriptors | ( | snd_mixer_t * | mixer,
|  | struct pollfd * | pfds,
|  | unsigned int | space
| ) |  |

get poll descriptors

Parameters

  mixer | Mixer handle
  pfds | array of poll descriptors
  space | space in the poll descriptor array

Returns
  count of filled descriptors

int snd_mixer_poll_descriptors_count | ( | snd_mixer_t * | mixer | ) |

get count of poll descriptors for mixer handle

Parameters

  mixer | Mixer handle

Returns
  count of poll descriptors

int snd_mixer_poll_descriptors_revents | ( | snd_mixer_t * | mixer,
|  | struct pollfd * | pfds,
|  | unsigned int | nfds,
|  | unsigned short * | revents
| ) |  |

get returned events from poll descriptors

Parameters

  mixer | Mixer 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_mixer_set_callback | ( | snd_mixer_t * | obj,
|  | snd_mixer_callback_t | val
| ) |  |

Set callback function for a mixer.

Parameters

  obj | mixer handle
  val | callback function

void snd_mixer_set_callback_private | ( | snd_mixer_t * | mixer,
|  | void * | val
| ) |  |

Set callback private value for a mixer.

Parameters

  mixer | mixer handle
  val | callback private value

int snd_mixer_set_compare | ( | snd_mixer_t * | mixer,
|  | snd_mixer_compare_t | compare
| ) |  |

Change mixer compare function and reorder elements.

Parameters

  mixer | Mixer handle
  compare | Element compare function

Returns
  0 on success otherwise a negative error code

int snd_mixer_wait | ( | snd_mixer_t * | mixer,
|  | int | timeout
| ) |  |

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

Parameters

  mixer | Mixer handle
  timeout | maximum time in milliseconds to wait

Returns
  0 otherwise a negative error code on failure