ALSA project - the C library reference: Control Interface

ALSA project - the C library reference

Loading...
Searching...
No Matches
Topics | Files | Data Structures | Macros | Typedefs | Enumerations | Functions
Control Interface

## Topics
| High level Control Interface
| Setup Control Interface

## Files
file | control_plugin.c
| Control Interface.

## Data Structures
struct | snd_aes_iec958_t

## Macros
#define | SND_CONTROL_DLSYM_VERSION _dlsym_control_001
#define | SND_CTL_EVENT_MASK_REMOVE
#define | SND_CTL_EVENT_MASK_VALUE
#define | SND_CTL_EVENT_MASK_INFO
#define | SND_CTL_EVENT_MASK_ADD
#define | SND_CTL_EVENT_MASK_TLV
#define | SND_CTL_NAME_NONE ""
#define | SND_CTL_NAME_PLAYBACK "Playback "
#define | SND_CTL_NAME_CAPTURE "Capture "
#define | SND_CTL_NAME_IEC958_NONE ""
#define | SND_CTL_NAME_IEC958_SWITCH "Switch"
#define | SND_CTL_NAME_IEC958_VOLUME "Volume"
#define | SND_CTL_NAME_IEC958_DEFAULT "Default"
#define | SND_CTL_NAME_IEC958_MASK "Mask"
#define | SND_CTL_NAME_IEC958_CON_MASK "Con Mask"
#define | SND_CTL_NAME_IEC958_PRO_MASK "Pro Mask"
#define | SND_CTL_NAME_IEC958_PCM_STREAM "PCM Stream"
#define | SND_CTL_NAME_IEC958(expl, direction, what) "IEC958 " expl SND_CTL_NAME_##direction SND_CTL_NAME_IEC958_##what
#define | SND_CTL_POWER_MASK 0xff00
#define | SND_CTL_POWER_D0 0x0000
#define | SND_CTL_POWER_D1 0x0100
#define | SND_CTL_POWER_D2 0x0200
#define | SND_CTL_POWER_D3 0x0300
#define | SND_CTL_POWER_D3hot (SND_CTL_POWER_D3|0x0000)
#define | SND_CTL_POWER_D3cold (SND_CTL_POWER_D3|0x0001)
#define | SND_CTL_TLVT_CONTAINER 0x0000
#define | SND_CTL_TLVT_DB_SCALE 0x0001
#define | SND_CTL_TLVT_DB_LINEAR 0x0002
#define | SND_CTL_TLVT_DB_RANGE 0x0003
#define | SND_CTL_TLVT_DB_MINMAX 0x0004
#define | SND_CTL_TLVT_DB_MINMAX_MUTE 0x0005
#define | SND_CTL_TLV_DB_GAIN_MUTE -9999999
#define | SND_CTL_TLVT_CHMAP_FIXED 0x00101
#define | SND_CTL_TLVT_CHMAP_VAR 0x00102
#define | SND_CTL_TLVT_CHMAP_PAIRED 0x00103
#define | SND_CTL_NONBLOCK
#define | SND_CTL_ASYNC
#define | SND_CTL_READONLY
#define | SND_CTL_EINTR
#define | SND_SCTL_NOFREE 0x0001
#define | snd_ctl_elem_id_alloca(ptr)
| allocate an invalid snd_ctl_elem_id_t using standard alloca
#define | snd_ctl_card_info_alloca(ptr)
| Allocate an invalid snd_ctl_card_info_t on the stack.
#define | snd_ctl_event_alloca(ptr)
| allocate an invalid snd_ctl_event_t using standard alloca
#define | snd_ctl_elem_list_alloca(ptr)
| Allocate a snd_ctl_elem_list_t using standard alloca.
#define | snd_ctl_elem_info_alloca(ptr)
| allocate an invalid snd_ctl_elem_info_t using standard alloca
#define | snd_ctl_elem_value_alloca(ptr)
| Allocate an invalid snd_ctl_elem_value_t on the stack.

## Typedefs
typedef struct _snd_ctl_card_info | snd_ctl_card_info_t
| CTL card info container.
typedef struct _snd_ctl_elem_id | snd_ctl_elem_id_t
typedef struct _snd_ctl_elem_list | snd_ctl_elem_list_t
typedef struct _snd_ctl_elem_info | snd_ctl_elem_info_t
typedef struct _snd_ctl_elem_value | snd_ctl_elem_value_t
typedef struct _snd_ctl_event | snd_ctl_event_t
typedef struct _snd_ctl | snd_ctl_t
typedef struct _snd_sctl | snd_sctl_t

## Enumerations
enum | snd_ctl_elem_type_t { SND_CTL_ELEM_TYPE_NONE = 0 , SND_CTL_ELEM_TYPE_BOOLEAN , SND_CTL_ELEM_TYPE_INTEGER , SND_CTL_ELEM_TYPE_ENUMERATED , SND_CTL_ELEM_TYPE_BYTES , SND_CTL_ELEM_TYPE_IEC958 , SND_CTL_ELEM_TYPE_INTEGER64 , SND_CTL_ELEM_TYPE_LAST = SND_CTL_ELEM_TYPE_INTEGER64 }
enum | snd_ctl_elem_iface_t { SND_CTL_ELEM_IFACE_CARD = 0 , SND_CTL_ELEM_IFACE_HWDEP , SND_CTL_ELEM_IFACE_MIXER , SND_CTL_ELEM_IFACE_PCM , SND_CTL_ELEM_IFACE_RAWMIDI , SND_CTL_ELEM_IFACE_TIMER , SND_CTL_ELEM_IFACE_SEQUENCER , SND_CTL_ELEM_IFACE_LAST = SND_CTL_ELEM_IFACE_SEQUENCER }
enum | snd_ctl_event_type_t { SND_CTL_EVENT_ELEM = 0 , SND_CTL_EVENT_LAST = SND_CTL_EVENT_ELEM }
enum | snd_ctl_type_t { SND_CTL_TYPE_HW , SND_CTL_TYPE_SHM , SND_CTL_TYPE_INET , SND_CTL_TYPE_EXT , SND_CTL_TYPE_REMAP }

## Functions
int | snd_card_load (int card)
| Try to load the driver for a card.
int | snd_card_next (int *card)
| Iterate over physical sound cards.
int | snd_card_get_index (const char *name)
| Convert a card string to the card index.
int | snd_card_get_name (int card, char **name)
| Obtain the card name.
int | snd_card_get_longname (int card, char **name)
| Obtain the card long name.
int | snd_ctl_open (snd_ctl_t **ctl, const char *name, int mode)
| Opens a sound card.
int | snd_ctl_open_lconf (snd_ctl_t **ctl, const char *name, int mode, snd_config_t *lconf)
| Opens a CTL using local configuration.
int | snd_ctl_open_fallback (snd_ctl_t **ctl, snd_config_t *root, const char *name, const char *orig_name, int mode)
| Opens a fallback CTL.
int | snd_ctl_close (snd_ctl_t *ctl)
| close CTL handle
int | snd_ctl_nonblock (snd_ctl_t *ctl, int nonblock)
| set nonblock mode
int | snd_async_add_ctl_handler (snd_async_handler_t **handler, snd_ctl_t *ctl, snd_async_callback_t callback, void *private_data)
| Add an async handler for a CTL.
snd_ctl_t * | snd_async_handler_get_ctl (snd_async_handler_t *handler)
| Return CTL handle related to an async handler.
int | snd_ctl_poll_descriptors_count (snd_ctl_t *ctl)
| get count of poll descriptors for CTL handle
int | snd_ctl_poll_descriptors (snd_ctl_t *ctl, struct pollfd *pfds, unsigned int space)
| get poll descriptors
int | snd_ctl_poll_descriptors_revents (snd_ctl_t *ctl, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
| get returned events from poll descriptors
int | snd_ctl_subscribe_events (snd_ctl_t *ctl, int subscribe)
| Ask to be informed about events (poll, snd_async_add_ctl_handler, snd_ctl_read)
int | snd_ctl_card_info (snd_ctl_t *ctl, snd_ctl_card_info_t *info)
| Get information about the sound card.
int | snd_ctl_elem_list (snd_ctl_t *ctl, snd_ctl_elem_list_t *list)
| Get a list of element identifiers.
int | snd_ctl_elem_info (snd_ctl_t *ctl, snd_ctl_elem_info_t *info)
| Get CTL element information.
int | snd_ctl_elem_read (snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
| Get CTL element value.
int | snd_ctl_elem_write (snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
| Set CTL element value.
int | snd_ctl_elem_lock (snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
| Lock CTL element.
int | snd_ctl_elem_unlock (snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
| Unlock CTL element.
int | snd_ctl_elem_tlv_read (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int *tlv, unsigned int tlv_size)
| Read structured data from an element set to given buffer.
int | snd_ctl_elem_tlv_write (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, const unsigned int *tlv)
| Write structured data from given buffer to an element set.
int | snd_ctl_elem_tlv_command (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, const unsigned int *tlv)
| Process structured data from given buffer for an element set.
int | snd_ctl_set_power_state (snd_ctl_t *ctl, unsigned int state)
| Set Power State to given SND_CTL_POWER_* value and do the power management.
int | snd_ctl_get_power_state (snd_ctl_t *ctl, unsigned int *state)
| Get actual Power State.
int | snd_ctl_read (snd_ctl_t *ctl, snd_ctl_event_t *event)
| Read an event.
int | snd_ctl_wait (snd_ctl_t *ctl, int timeout)
| Wait for a CTL to become ready (i.e. at least one event pending)
const char * | snd_ctl_name (snd_ctl_t *ctl)
| get identifier of CTL handle
snd_ctl_type_t | snd_ctl_type (snd_ctl_t *ctl)
| get type of CTL handle
const char * | snd_ctl_elem_type_name (snd_ctl_elem_type_t type)
| get name of a CTL element type
const char * | snd_ctl_elem_iface_name (snd_ctl_elem_iface_t iface)
| get name of a CTL element related interface
const char * | snd_ctl_event_type_name (snd_ctl_event_type_t type)
| get name of a CTL event type
unsigned int | snd_ctl_event_elem_get_mask (const snd_ctl_event_t *obj)
| Get event mask for an element related event.
unsigned int | snd_ctl_event_elem_get_numid (const snd_ctl_event_t *obj)
| Get element numeric identifier for an element related event.
void | snd_ctl_event_elem_get_id (const snd_ctl_event_t *obj, snd_ctl_elem_id_t *ptr)
| Get CTL element identifier for an element related event.
snd_ctl_elem_iface_t | snd_ctl_event_elem_get_interface (const snd_ctl_event_t *obj)
| Get interface part of CTL element identifier for an element related event.
unsigned int | snd_ctl_event_elem_get_device (const snd_ctl_event_t *obj)
| Get device part of CTL element identifier for an element related event.
unsigned int | snd_ctl_event_elem_get_subdevice (const snd_ctl_event_t *obj)
| Get subdevice part of CTL element identifier for an element related event.
const char * | snd_ctl_event_elem_get_name (const snd_ctl_event_t *obj)
| Get name part of CTL element identifier for an element related event.
unsigned int | snd_ctl_event_elem_get_index (const snd_ctl_event_t *obj)
| Get index part of CTL element identifier for an element related event.
int | snd_ctl_elem_list_alloc_space (snd_ctl_elem_list_t *obj, unsigned int entries)
| allocate space for CTL element identifiers list
void | snd_ctl_elem_list_free_space (snd_ctl_elem_list_t *obj)
| free previously allocated space for CTL element identifiers list
char * | snd_ctl_ascii_elem_id_get (snd_ctl_elem_id_t *id)
| return ASCII CTL element identifier name
int | snd_ctl_ascii_elem_id_parse (snd_ctl_elem_id_t *dst, const char *str)
| parse ASCII string as CTL element identifier
int | snd_ctl_ascii_value_parse (snd_ctl_t *handle, snd_ctl_elem_value_t *dst, snd_ctl_elem_info_t *info, const char *value)
| parse ASCII string as CTL element value
size_t | snd_ctl_elem_id_sizeof (void)
| get size of snd_ctl_elem_id_t
int | snd_ctl_elem_id_malloc (snd_ctl_elem_id_t **ptr)
| allocate an invalid snd_ctl_elem_id_t using standard malloc
void | snd_ctl_elem_id_free (snd_ctl_elem_id_t *obj)
| frees a previously allocated snd_ctl_elem_id_t
void | snd_ctl_elem_id_clear (snd_ctl_elem_id_t *obj)
| clear given snd_ctl_elem_id_t object
void | snd_ctl_elem_id_copy (snd_ctl_elem_id_t *dst, const snd_ctl_elem_id_t *src)
| copy one snd_ctl_elem_id_t to another
int | snd_ctl_elem_id_compare_numid (const snd_ctl_elem_id_t *id1, const snd_ctl_elem_id_t *id2)
| compare one snd_ctl_elem_id_t to another using numid
int | snd_ctl_elem_id_compare_set (const snd_ctl_elem_id_t *id1, const snd_ctl_elem_id_t *id2)
| compare one snd_ctl_elem_id_t to another
unsigned int | snd_ctl_elem_id_get_numid (const snd_ctl_elem_id_t *obj)
| Get numeric identifier from a CTL element identifier.
snd_ctl_elem_iface_t | snd_ctl_elem_id_get_interface (const snd_ctl_elem_id_t *obj)
| Get interface part of a CTL element identifier.
unsigned int | snd_ctl_elem_id_get_device (const snd_ctl_elem_id_t *obj)
| Get device part of a CTL element identifier.
unsigned int | snd_ctl_elem_id_get_subdevice (const snd_ctl_elem_id_t *obj)
| Get subdevice part of a CTL element identifier.
const char * | snd_ctl_elem_id_get_name (const snd_ctl_elem_id_t *obj)
| Get name part of a CTL element identifier.
unsigned int | snd_ctl_elem_id_get_index (const snd_ctl_elem_id_t *obj)
| Get index part of a CTL element identifier.
void | snd_ctl_elem_id_set_numid (snd_ctl_elem_id_t *obj, unsigned int val)
| Set numeric identifier for a CTL element identifier.
void | snd_ctl_elem_id_set_interface (snd_ctl_elem_id_t *obj, snd_ctl_elem_iface_t val)
| Set interface part for a CTL element identifier.
void | snd_ctl_elem_id_set_device (snd_ctl_elem_id_t *obj, unsigned int val)
| Set device part for a CTL element identifier.
void | snd_ctl_elem_id_set_subdevice (snd_ctl_elem_id_t *obj, unsigned int val)
| Set subdevice part for a CTL element identifier.
void | snd_ctl_elem_id_set_name (snd_ctl_elem_id_t *obj, const char *val)
| Set name part for a CTL element identifier.
void | snd_ctl_elem_id_set_index (snd_ctl_elem_id_t *obj, unsigned int val)
| Set index part for a CTL element identifier.
size_t | snd_ctl_card_info_sizeof (void)
| get size of snd_ctl_card_info_t.
int | snd_ctl_card_info_malloc (snd_ctl_card_info_t **ptr)
| Allocate an invalid snd_ctl_card_info_t on the heap.
void | snd_ctl_card_info_free (snd_ctl_card_info_t *obj)
| Free an snd_ctl_card_info_t previously allocated using snd_ctl_card_info_malloc().
void | snd_ctl_card_info_clear (snd_ctl_card_info_t *obj)
| Clear given card info object.
void | snd_ctl_card_info_copy (snd_ctl_card_info_t *dst, const snd_ctl_card_info_t *src)
| Bitwise copy of a snd_ctl_card_info_t object.
int | snd_ctl_card_info_get_card (const snd_ctl_card_info_t *obj)
| Get the sound card index from the given info object.
const char * | snd_ctl_card_info_get_id (const snd_ctl_card_info_t *obj)
| Get the sound card ID from the given info object.
const char * | snd_ctl_card_info_get_driver (const snd_ctl_card_info_t *obj)
| Get the sound card driver from the given info object.
const char * | snd_ctl_card_info_get_name (const snd_ctl_card_info_t *obj)
| Get the sound card name from the given info object.
const char * | snd_ctl_card_info_get_longname (const snd_ctl_card_info_t *obj)
| Get the sound cards long name from the given info object.
const char * | snd_ctl_card_info_get_mixername (const snd_ctl_card_info_t *obj)
| Get the sound card mixer name from the given info object.
const char * | snd_ctl_card_info_get_components (const snd_ctl_card_info_t *obj)
| Get the sound cards "components" property from the given info object.
size_t | snd_ctl_event_sizeof (void)
| get size of snd_ctl_event_t
int | snd_ctl_event_malloc (snd_ctl_event_t **ptr)
| allocate an invalid snd_ctl_event_t using standard malloc
void | snd_ctl_event_free (snd_ctl_event_t *obj)
| frees a previously allocated snd_ctl_event_t
void | snd_ctl_event_clear (snd_ctl_event_t *obj)
| clear given snd_ctl_event_t object
void | snd_ctl_event_copy (snd_ctl_event_t *dst, const snd_ctl_event_t *src)
| copy one snd_ctl_event_t to another
snd_ctl_event_type_t | snd_ctl_event_get_type (const snd_ctl_event_t *obj)
| Get type of a CTL event.
size_t | snd_ctl_elem_list_sizeof (void)
| get size of snd_ctl_elem_list_t.
int | snd_ctl_elem_list_malloc (snd_ctl_elem_list_t **ptr)
| allocate a snd_ctl_elem_list_t using standard malloc.
void | snd_ctl_elem_list_free (snd_ctl_elem_list_t *obj)
| frees a previously allocated snd_ctl_elem_list_t.
void | snd_ctl_elem_list_clear (snd_ctl_elem_list_t *obj)
| Clear given snd_ctl_elem_list_t object.
void | snd_ctl_elem_list_copy (snd_ctl_elem_list_t *dst, const snd_ctl_elem_list_t *src)
| copy one snd_ctl_elem_list_t to another.
void | snd_ctl_elem_list_set_offset (snd_ctl_elem_list_t *obj, unsigned int val)
| Set index of first wanted CTL element identifier in a CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_used (const snd_ctl_elem_list_t *obj)
| Get number of used entries in CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_count (const snd_ctl_elem_list_t *obj)
| Get total count of elements present in CTL device.
void | snd_ctl_elem_list_get_id (const snd_ctl_elem_list_t *obj, unsigned int idx, snd_ctl_elem_id_t *ptr)
| Get CTL element identifier for an entry of a CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_numid (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get CTL element numeric identifier for an entry of a CTL element identifiers list.
snd_ctl_elem_iface_t | snd_ctl_elem_list_get_interface (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get interface part of CTL element identifier for an entry of a CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_device (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get the device part of CTL element identifier for an entry of a CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_subdevice (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get subdevice part of CTL element identifier for an entry of a CTL element identifiers list.
const char * | snd_ctl_elem_list_get_name (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get name part of CTL element identifier for an entry of a CTL element identifiers list.
unsigned int | snd_ctl_elem_list_get_index (const snd_ctl_elem_list_t *obj, unsigned int idx)
| Get index part of CTL element identifier for an entry of a CTL element identifiers list.
size_t | snd_ctl_elem_info_sizeof (void)
| get size of snd_ctl_elem_info_t
int | snd_ctl_elem_info_malloc (snd_ctl_elem_info_t **ptr)
| allocate an invalid snd_ctl_elem_info_t using standard malloc
void | snd_ctl_elem_info_free (snd_ctl_elem_info_t *obj)
| frees a previously allocated snd_ctl_elem_info_t
void | snd_ctl_elem_info_clear (snd_ctl_elem_info_t *obj)
| clear given snd_ctl_elem_info_t object
void | snd_ctl_elem_info_copy (snd_ctl_elem_info_t *dst, const snd_ctl_elem_info_t *src)
| copy one snd_ctl_elem_info_t to another
snd_ctl_elem_type_t | snd_ctl_elem_info_get_type (const snd_ctl_elem_info_t *obj)
| Get type from a CTL element id/info.
int | snd_ctl_elem_info_is_readable (const snd_ctl_elem_info_t *obj)
| Get info about readability from a CTL element id/info.
int | snd_ctl_elem_info_is_writable (const snd_ctl_elem_info_t *obj)
| Get info about writability from a CTL element id/info.
int | snd_ctl_elem_info_is_volatile (const snd_ctl_elem_info_t *obj)
| Get info about notification feasibility from a CTL element id/info.
int | snd_ctl_elem_info_is_inactive (const snd_ctl_elem_info_t *obj)
| Get info about status from a CTL element id/info.
int | snd_ctl_elem_info_is_locked (const snd_ctl_elem_info_t *obj)
| Get info whether an element is locked.
int | snd_ctl_elem_info_is_tlv_readable (const snd_ctl_elem_info_t *obj)
| Get info about TLV readability from a CTL element id/info.
int | snd_ctl_elem_info_is_tlv_writable (const snd_ctl_elem_info_t *obj)
| Get info about TLV writeability from a CTL element id/info.
int | snd_ctl_elem_info_is_tlv_commandable (const snd_ctl_elem_info_t *obj)
| Get info about TLV command possibility from a CTL element id/info.
int | snd_ctl_elem_info_is_owner (const snd_ctl_elem_info_t *obj)
| Get info if I own an element.
int | snd_ctl_elem_info_is_user (const snd_ctl_elem_info_t *obj)
| Get info if it's a user element.
pid_t | snd_ctl_elem_info_get_owner (const snd_ctl_elem_info_t *obj)
| Get owner of a locked element.
unsigned int | snd_ctl_elem_info_get_count (const snd_ctl_elem_info_t *obj)
| Get number of value entries from a CTL element id/info.
long | snd_ctl_elem_info_get_min (const snd_ctl_elem_info_t *obj)
| Get minimum value from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.
long | snd_ctl_elem_info_get_max (const snd_ctl_elem_info_t *obj)
| Get maximum value from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.
long | snd_ctl_elem_info_get_step (const snd_ctl_elem_info_t *obj)
| Get value step from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.
long long | snd_ctl_elem_info_get_min64 (const snd_ctl_elem_info_t *obj)
| Get minimum value from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.
long long | snd_ctl_elem_info_get_max64 (const snd_ctl_elem_info_t *obj)
| Get maximum value from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.
long long | snd_ctl_elem_info_get_step64 (const snd_ctl_elem_info_t *obj)
| Get value step from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.
unsigned int | snd_ctl_elem_info_get_items (const snd_ctl_elem_info_t *obj)
| Get number of items available from a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.
void | snd_ctl_elem_info_set_item (snd_ctl_elem_info_t *obj, unsigned int val)
| Select item in a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.
const char * | snd_ctl_elem_info_get_item_name (const snd_ctl_elem_info_t *obj)
| Get name for selected item in a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.
int | snd_ctl_elem_info_get_dimensions (const snd_ctl_elem_info_t *obj)
| Get count of dimensions for given element.
int | snd_ctl_elem_info_get_dimension (const snd_ctl_elem_info_t *obj, unsigned int idx)
| Get specified of dimension width for given element.
int | snd_ctl_elem_info_set_dimension (snd_ctl_elem_info_t *info, const int dimension[4])
| Set width to a specified dimension level of given element information.
void | snd_ctl_elem_info_get_id (const snd_ctl_elem_info_t *obj, snd_ctl_elem_id_t *ptr)
| Get CTL element identifier of a CTL element id/info.
unsigned int | snd_ctl_elem_info_get_numid (const snd_ctl_elem_info_t *obj)
| Get element numeric identifier of a CTL element id/info.
snd_ctl_elem_iface_t | snd_ctl_elem_info_get_interface (const snd_ctl_elem_info_t *obj)
| Get interface part of CTL element identifier of a CTL element id/info.
unsigned int | snd_ctl_elem_info_get_device (const snd_ctl_elem_info_t *obj)
| Get device part of CTL element identifier of a CTL element id/info.
unsigned int | snd_ctl_elem_info_get_subdevice (const snd_ctl_elem_info_t *obj)
| Get subdevice part of CTL element identifier of a CTL element id/info.
const char * | snd_ctl_elem_info_get_name (const snd_ctl_elem_info_t *obj)
| Get name part of CTL element identifier of a CTL element id/info.
unsigned int | snd_ctl_elem_info_get_index (const snd_ctl_elem_info_t *obj)
| Get index part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_id (snd_ctl_elem_info_t *obj, const snd_ctl_elem_id_t *ptr)
| Set CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_numid (snd_ctl_elem_info_t *obj, unsigned int val)
| Set element numeric identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_interface (snd_ctl_elem_info_t *obj, snd_ctl_elem_iface_t val)
| Set interface part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_device (snd_ctl_elem_info_t *obj, unsigned int val)
| Set device part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_subdevice (snd_ctl_elem_info_t *obj, unsigned int val)
| Set subdevice part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_name (snd_ctl_elem_info_t *obj, const char *val)
| Set name part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_index (snd_ctl_elem_info_t *obj, unsigned int val)
| Set index part of CTL element identifier of a CTL element id/info.
void | snd_ctl_elem_info_set_read_write (snd_ctl_elem_info_t *obj, int rval, int wval)
| Set readability/writeability parameter of a CTL element id/info.
void | snd_ctl_elem_info_set_tlv_read_write (snd_ctl_elem_info_t *obj, int rval, int wval)
| Set TLV readability/writeability parameter of a CTL element id/info.
void | snd_ctl_elem_info_set_inactive (snd_ctl_elem_info_t *obj, int val)
| Set inactive parameter of a CTL element id/info.
int | snd_ctl_add_integer_elem_set (snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count, long min, long max, long step)
| Create and add some user-defined control elements of integer type.
int | snd_ctl_add_integer64_elem_set (snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count, long long min, long long max, long long step)
| Create and add some user-defined control elements of integer64 type.
int | snd_ctl_add_boolean_elem_set (snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count)
| Create and add some user-defined control elements of boolean type.
int | snd_ctl_add_enumerated_elem_set (snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count, unsigned int items, const char *const labels[])
| Create and add some user-defined control elements of enumerated type.
int | snd_ctl_add_bytes_elem_set (snd_ctl_t *ctl, snd_ctl_elem_info_t *info, unsigned int element_count, unsigned int member_count)
| Create and add some user-defined control elements of bytes type.
int | snd_ctl_elem_add_integer (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long imin, long imax, long istep)
| Create and add an user-defined control element of integer type.
int | snd_ctl_elem_add_integer64 (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, long long imin, long long imax, long long istep)
| Create and add an user-defined control element of integer64 type.
int | snd_ctl_elem_add_boolean (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count)
| Create and add an user-defined control element of boolean type.
int | snd_ctl_elem_add_enumerated (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, unsigned int count, unsigned int items, const char *const names[])
| Create and add a user-defined control element of enumerated type.
int | snd_ctl_elem_add_iec958 (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id)
| Create and add a user-defined control element of IEC958 type.
int | snd_ctl_elem_remove (snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
| Remove an user CTL element.
size_t | snd_ctl_elem_value_sizeof (void)
| Get size of data structure for an element.
int | snd_ctl_elem_value_malloc (snd_ctl_elem_value_t **ptr)
| Allocate an invalid snd_ctl_elem_value_t on the heap.
void | snd_ctl_elem_value_free (snd_ctl_elem_value_t *obj)
| Free an snd_ctl_elem_value_t previously allocated using snd_ctl_elem_value_malloc().
void | snd_ctl_elem_value_clear (snd_ctl_elem_value_t *obj)
| Clear given data of an element.
void | snd_ctl_elem_value_copy (snd_ctl_elem_value_t *dst, const snd_ctl_elem_value_t *src)
| Bitwise copy of a snd_ctl_elem_value_t value.
int | snd_ctl_elem_value_compare (snd_ctl_elem_value_t *left, const snd_ctl_elem_value_t *right)
| Compare two snd_ctl_elem_value_t values, bytewise.
void | snd_ctl_elem_value_get_id (const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr)
| Get the element identifier from the given element value.
unsigned int | snd_ctl_elem_value_get_numid (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'numid' part from the given element value.
snd_ctl_elem_iface_t | snd_ctl_elem_value_get_interface (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'interface' part from the given element value.
unsigned int | snd_ctl_elem_value_get_device (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'device' part from the given element value.
unsigned int | snd_ctl_elem_value_get_subdevice (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'subdevice' part from the given element value.
const char * | snd_ctl_elem_value_get_name (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'name' part from the given element value.
unsigned int | snd_ctl_elem_value_get_index (const snd_ctl_elem_value_t *obj)
| Get the identifiers 'index' part from the given element value.
void | snd_ctl_elem_value_set_id (snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr)
| Set the element identifier within the given element value.
void | snd_ctl_elem_value_set_numid (snd_ctl_elem_value_t *obj, unsigned int val)
| Set the identifiers 'numid' part within the given element value.
void | snd_ctl_elem_value_set_interface (snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val)
| Set the identifiers 'interface' part within the given element value.
void | snd_ctl_elem_value_set_device (snd_ctl_elem_value_t *obj, unsigned int val)
| Set the identifiers 'device' part within the given element value.
void | snd_ctl_elem_value_set_subdevice (snd_ctl_elem_value_t *obj, unsigned int val)
| Set the identifiers 'subdevice' part within the given element value.
void | snd_ctl_elem_value_set_name (snd_ctl_elem_value_t *obj, const char *val)
| Set the identifiers 'name' part within the given element value.
void | snd_ctl_elem_value_set_index (snd_ctl_elem_value_t *obj, unsigned int val)
| Set the identifiers 'index' part within the given element value.
int | snd_ctl_elem_value_get_boolean (const snd_ctl_elem_value_t *obj, unsigned int idx)
| Get an element members value.
long | snd_ctl_elem_value_get_integer (const snd_ctl_elem_value_t *obj, unsigned int idx)
| Get an element members value.
long long | snd_ctl_elem_value_get_integer64 (const snd_ctl_elem_value_t *obj, unsigned int idx)
| Get an element members value.
unsigned int | snd_ctl_elem_value_get_enumerated (const snd_ctl_elem_value_t *obj, unsigned int idx)
| Get an element members value.
unsigned char | snd_ctl_elem_value_get_byte (const snd_ctl_elem_value_t *obj, unsigned int idx)
| Get an element members value.
void | snd_ctl_elem_value_set_boolean (snd_ctl_elem_value_t *obj, unsigned int idx, long val)
| Set an element members value.
void | snd_ctl_elem_value_set_integer (snd_ctl_elem_value_t *obj, unsigned int idx, long val)
| Set an element members value.
void | snd_ctl_elem_value_set_integer64 (snd_ctl_elem_value_t *obj, unsigned int idx, long long val)
| Set an element members value.
void | snd_ctl_elem_value_set_enumerated (snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val)
| Set an element members value.
void | snd_ctl_elem_value_set_byte (snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val)
| Set an element members value.
void | snd_ctl_elem_set_bytes (snd_ctl_elem_value_t *obj, void *data, size_t size)
| Replace the data stored within the element.
const void * | snd_ctl_elem_value_get_bytes (const snd_ctl_elem_value_t *obj)
| Get the data stored within the element.
void | snd_ctl_elem_value_get_iec958 (const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr)
| Get an elements IEC958 data.
void | snd_ctl_elem_value_set_iec958 (snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr)
| Set an elements IEC958 data.
int | snd_tlv_parse_dB_info (unsigned int *tlv, unsigned int tlv_size, unsigned int **db_tlvp)
| Parse TLV stream and retrieve dB information.
int | snd_tlv_get_dB_range (unsigned int *tlv, long rangemin, long rangemax, long *min, long *max)
| Get the dB min/max values.
int | snd_tlv_convert_to_dB (unsigned int *tlv, long rangemin, long rangemax, long volume, long *db_gain)
| Convert the given raw volume value to a dB gain.
int | snd_tlv_convert_from_dB (unsigned int *tlv, long rangemin, long rangemax, long db_gain, long *value, int xdir)
| Convert from dB gain to the corresponding raw value.
int | snd_ctl_get_dB_range (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long *min, long *max)
| Get the dB min/max values on the given control element.
int | snd_ctl_convert_to_dB (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long volume, long *db_gain)
| Convert the volume value to dB on the given control element.
int | snd_ctl_convert_from_dB (snd_ctl_t *ctl, const snd_ctl_elem_id_t *id, long db_gain, long *value, int xdir)
| Convert from dB gain to the raw volume value on the given control element.

## Detailed Description

The control interface. See Control interface page for more details.

## Macro Definition Documentation

## ◆ SND_CONTROL_DLSYM_VERSION

#define SND_CONTROL_DLSYM_VERSION _dlsym_control_001

dlsym version for interface entry callback

## ◆ SND_CTL_ASYNC

#define SND_CTL_ASYNC

Async notification (flag for open mode)

## ◆ snd_ctl_card_info_alloca

#define snd_ctl_card_info_alloca | ( |  | ptr | ) |

Allocate an invalid snd_ctl_card_info_t on the stack.

Allocate space for a card info object on the stack. The allocated memory need not be freed, because it is on the stack.

See snd_ctl_card_info_t for details.

Parameters

  ptr | Pointer to a snd_ctl_elem_value_t pointer. The address of the allocated space will returned here.

## ◆ SND_CTL_EINTR

#define SND_CTL_EINTR

Return EINTR instead blocking (flag for open mode)

## ◆ snd_ctl_elem_id_alloca

#define snd_ctl_elem_id_alloca | ( |  | ptr | ) |

allocate an invalid snd_ctl_elem_id_t using standard alloca

Parameters

  ptr | returned pointer

## ◆ snd_ctl_elem_info_alloca

#define snd_ctl_elem_info_alloca | ( |  | ptr | ) |

allocate an invalid snd_ctl_elem_info_t using standard alloca

Parameters

  ptr | returned pointer

## ◆ snd_ctl_elem_list_alloca

#define snd_ctl_elem_list_alloca | ( |  | ptr | ) |

Allocate a snd_ctl_elem_list_t using standard alloca.

The memory is allocated on the stack and will automatically be released when the stack unwinds (i.e. no free() is needed).

Parameters

  ptr | Pointer to allocated memory.

## ◆ snd_ctl_elem_value_alloca

#define snd_ctl_elem_value_alloca | ( |  | ptr | ) |

Allocate an invalid snd_ctl_elem_value_t on the stack.

Allocate space for a value object on the stack. The allocated memory need not be freed, because it is on the stack.

See snd_ctl_elem_value_t for details.

Parameters

  ptr | Pointer to a snd_ctl_elem_value_t pointer. The address of the allocated space will returned here.

## ◆ snd_ctl_event_alloca

#define snd_ctl_event_alloca | ( |  | ptr | ) |

allocate an invalid snd_ctl_event_t using standard alloca

Parameters

  ptr | returned pointer

## ◆ SND_CTL_EVENT_MASK_ADD

#define SND_CTL_EVENT_MASK_ADD

Element has been added

## ◆ SND_CTL_EVENT_MASK_INFO

#define SND_CTL_EVENT_MASK_INFO

Element info has been changed

## ◆ SND_CTL_EVENT_MASK_REMOVE

#define SND_CTL_EVENT_MASK_REMOVE

Element has been removed (Warning: test this first and if set don't test the other masks)

## ◆ SND_CTL_EVENT_MASK_TLV

#define SND_CTL_EVENT_MASK_TLV

Element's TLV value has been changed

## ◆ SND_CTL_EVENT_MASK_VALUE

#define SND_CTL_EVENT_MASK_VALUE

Element value has been changed

## ◆ SND_CTL_NAME_CAPTURE

#define SND_CTL_NAME_CAPTURE "Capture "

CTL name helper

## ◆ SND_CTL_NAME_IEC958

#define SND_CTL_NAME_IEC958 | ( |  | expl,
|  |  | direction,
|  |  | what ) "IEC958 " expl SND_CTL_NAME_##direction SND_CTL_NAME_IEC958_##what

Element name for IEC958 (S/PDIF)

## ◆ SND_CTL_NAME_IEC958_CON_MASK

#define SND_CTL_NAME_IEC958_CON_MASK "Con Mask"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_DEFAULT

#define SND_CTL_NAME_IEC958_DEFAULT "Default"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_MASK

#define SND_CTL_NAME_IEC958_MASK "Mask"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_NONE

#define SND_CTL_NAME_IEC958_NONE ""

CTL name helper

## ◆ SND_CTL_NAME_IEC958_PCM_STREAM

#define SND_CTL_NAME_IEC958_PCM_STREAM "PCM Stream"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_PRO_MASK

#define SND_CTL_NAME_IEC958_PRO_MASK "Pro Mask"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_SWITCH

#define SND_CTL_NAME_IEC958_SWITCH "Switch"

CTL name helper

## ◆ SND_CTL_NAME_IEC958_VOLUME

#define SND_CTL_NAME_IEC958_VOLUME "Volume"

CTL name helper

## ◆ SND_CTL_NAME_NONE

#define SND_CTL_NAME_NONE ""

CTL name helper

## ◆ SND_CTL_NAME_PLAYBACK

#define SND_CTL_NAME_PLAYBACK "Playback "

CTL name helper

## ◆ SND_CTL_NONBLOCK

#define SND_CTL_NONBLOCK

Non blocking mode (flag for open mode)

## ◆ SND_CTL_POWER_D0

#define SND_CTL_POWER_D0 0x0000

ACPI/PCI Power State D0

## ◆ SND_CTL_POWER_D1

#define SND_CTL_POWER_D1 0x0100

ACPI/PCI Power State D1

## ◆ SND_CTL_POWER_D2

#define SND_CTL_POWER_D2 0x0200

ACPI/PCI Power State D2

## ◆ SND_CTL_POWER_D3

#define SND_CTL_POWER_D3 0x0300

ACPI/PCI Power State D3

## ◆ SND_CTL_POWER_D3cold

#define SND_CTL_POWER_D3cold (SND_CTL_POWER_D3|0x0001)

ACPI/PCI Power State D3cold

## ◆ SND_CTL_POWER_D3hot

#define SND_CTL_POWER_D3hot (SND_CTL_POWER_D3|0x0000)

ACPI/PCI Power State D3hot

## ◆ SND_CTL_POWER_MASK

#define SND_CTL_POWER_MASK 0xff00

Mask for the major Power State identifier

## ◆ SND_CTL_READONLY

#define SND_CTL_READONLY

Read only (flag for open mode)

## ◆ SND_CTL_TLV_DB_GAIN_MUTE

#define SND_CTL_TLV_DB_GAIN_MUTE -9999999

Mute state

## ◆ SND_CTL_TLVT_CHMAP_FIXED

#define SND_CTL_TLVT_CHMAP_FIXED 0x00101

TLV type - fixed channel map positions

## ◆ SND_CTL_TLVT_CHMAP_PAIRED

#define SND_CTL_TLVT_CHMAP_PAIRED 0x00103

TLV type - pair-wise swappable channel map positions

## ◆ SND_CTL_TLVT_CHMAP_VAR

#define SND_CTL_TLVT_CHMAP_VAR 0x00102

TLV type - freely swappable channel map positions

## ◆ SND_CTL_TLVT_CONTAINER

#define SND_CTL_TLVT_CONTAINER 0x0000

TLV type - Container

## ◆ SND_CTL_TLVT_DB_LINEAR

#define SND_CTL_TLVT_DB_LINEAR 0x0002

TLV type - linear volume

## ◆ SND_CTL_TLVT_DB_MINMAX

#define SND_CTL_TLVT_DB_MINMAX 0x0004

TLV type - dB scale specified by min/max values

## ◆ SND_CTL_TLVT_DB_MINMAX_MUTE

#define SND_CTL_TLVT_DB_MINMAX_MUTE 0x0005

TLV type - dB scale specified by min/max values (with mute)

## ◆ SND_CTL_TLVT_DB_RANGE

#define SND_CTL_TLVT_DB_RANGE 0x0003

TLV type - dB range container

## ◆ SND_CTL_TLVT_DB_SCALE

#define SND_CTL_TLVT_DB_SCALE 0x0001

TLV type - basic dB scale

## ◆ SND_SCTL_NOFREE

#define SND_SCTL_NOFREE 0x0001

Don't destroy the ctl handle when close

## Typedef Documentation

## ◆ snd_ctl_card_info_t

typedef struct _snd_ctl_card_info snd_ctl_card_info_t

CTL card info container.

This type contains meta information about a sound card, such as the index, name, longname, etc.

Memory management

Before using a snd_ctl_card_info_t object, it must be allocated using snd_ctl_card_info_alloca() or snd_ctl_card_info_malloc(). When using the latter, it must be freed again using snd_ctl_card_info_free().

A card info object can be zeroed out using snd_ctl_card_info_clear().

A card info object can be copied to another one using snd_ctl_card_info_copy().

Obtaining the Information

To obtain the card information, it must first be opened using snd_ctl_open(), and a snd_ctl_card_info_t container must be allocated. Then, the information can be read using snd_ctl_card_info_get_card().

Thereafter, the card properties can be read using the snd_ctl_card_info_get_*() functions.

## ◆ snd_ctl_elem_id_t

typedef struct _snd_ctl_elem_id snd_ctl_elem_id_t

CTL element identifier container

## ◆ snd_ctl_elem_info_t

typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t

CTL element info container

## ◆ snd_ctl_elem_list_t

typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t

CTL element list container

This is a list of CTL elements. The list contains management information (e.g. how many elements the sound card has) as well as the element identifiers. All functions which operate on the list are named snd_ctl_elem_list_*().

Memory management

There are two memory areas to deal with: The list container itself and the memory for the element identifiers.

To manage the area for the list container, the following functions are used:

- snd_ctl_elem_list_malloc() / snd_ctl_elem_list_free() to allocate and free memory on the heap, or
- snd_ctl_elem_list_alloca() to allocate the memory on the stack. This memory is auto-released when the stack is unwound.

To manage the space for the element identifiers, the snd_ctl_elem_list_alloc_space() and snd_ctl_elem_list_free_space() are used. Allocating the right amount of space can be achieved by first obtaining the number of elements and then calling snd_ctl_elem_list_alloc_space():

snd_ctl_elem_list_t* list;
int count;
// Initialise list
snd_ctl_elem_list_malloc(&list);
// Get number of elements
snd_ctl_elem_list(ctl, list);
count = snd_ctl_elem_list_get_count(list);
// Allocate space for identifiers
snd_ctl_elem_list_alloc_space(list, count);
// Get identifiers
snd_ctl_elem_list(ctl, list); // yes, this is same as above :)
// Do something useful with the list...
// Cleanup
snd_ctl_elem_list_free_space(list);
snd_ctl_elem_list_free(list);
snd_ctl_elem_list_get_count
unsigned int snd_ctl_elem_list_get_count(const snd_ctl_elem_list_t *obj)
Get total count of elements present in CTL device.
Definition control.c:2461
snd_ctl_elem_list_alloc_space
int snd_ctl_elem_list_alloc_space(snd_ctl_elem_list_t *obj, unsigned int entries)
allocate space for CTL element identifiers list
Definition control.c:1740
snd_ctl_elem_list_free_space
void snd_ctl_elem_list_free_space(snd_ctl_elem_list_t *obj)
free previously allocated space for CTL element identifiers list
Definition control.c:1760
snd_ctl_elem_list_free
void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj)
frees a previously allocated snd_ctl_elem_list_t.
Definition control.c:2384
snd_ctl_elem_list_t
struct _snd_ctl_elem_list snd_ctl_elem_list_t
Definition control.h:153
snd_ctl_elem_list_malloc
int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr)
allocate a snd_ctl_elem_list_t using standard malloc.
Definition control.c:2363
snd_ctl_elem_list
int snd_ctl_elem_list(snd_ctl_t *ctl, snd_ctl_elem_list_t *list)
Get a list of element identifiers.
Definition control.c:412

The Elements

The elements in the list are accessed using an index. This index is the location in the list; Don't confuse it with the 'index' of the element identifier. For example:

snd_ctl_elem_list_t list;
unsigned int element_index;
// Allocate space, fill list ...
element_index = snd_ctl_elem_list_get_index(&list, 2);
snd_ctl_elem_list_get_index
unsigned int snd_ctl_elem_list_get_index(const snd_ctl_elem_list_t *obj, unsigned int idx)
Get index part of CTL element identifier for an entry of a CTL element identifiers list.
Definition control.c:2551

This will access the 3rd element in the list (index=2) and get the elements index from the driver (which might be 13, for example).

## ◆ snd_ctl_elem_value_t

typedef struct _snd_ctl_elem_value snd_ctl_elem_value_t

CTL element value container.

Contains the value(s) (i.e. members) of a single element. All values of a given element are of the same type.

Memory management

To access a value, a snd_ctl_elem_value_t must be allocated using snd_ctl_elem_value_alloca() or snd_ctl_elem_value_malloc(). When using the latter, it must be freed again using snd_ctl_elem_value_free().

A value object can be zeroed out using snd_ctl_elem_value_clear().

A value object can be copied to another one using snd_ctl_elem_value_copy().

Identifier

Then, the ID must be filled. It is sufficient to fill only the numid, if known. Otherwise, interface type, device, subdevice, name, index must all be given. The following functions can be used to fill the ID:

- snd_ctl_elem_value_set_id(): Set the ID. Requires an snd_ctl_elem_id_t object.
- snd_ctl_elem_value_set_numid(): Set the numid.
- Or use all of the following:
  - snd_ctl_elem_value_set_interface()
  - snd_ctl_elem_value_set_device()
  - snd_ctl_elem_value_set_subdevice()
  - snd_ctl_elem_value_set_name()
  - snd_ctl_elem_value_set_index()

When communicating with the driver (snd_ctl_elem_read(), snd_ctl_elem_write()), and the numid was given, the interface, device, ... are filled (even if you set the before). When the numid is unset (i.e. it is 0), it is filled.

Communicating with the driver

After the value container was created and filled with the ID of the desired element, the value(s) can be fetched from the driver (and thus from the hardware) or written to the driver.

To fetch a value, use snd_ctl_elem_read(). Thereafter, use the snd_ctl_elem_value_get_*() functions to obtain the actual value.

To write a new value, first use a snd_ctl_elem_value_set_*() to set it, then call snd_ctl_elem_write() to write it to the driver.

## ◆ snd_ctl_event_t

typedef struct _snd_ctl_event snd_ctl_event_t

CTL event container

## ◆ snd_ctl_t

typedef struct _snd_ctl snd_ctl_t

CTL handle

## ◆ snd_sctl_t

typedef struct _snd_sctl snd_sctl_t

SCTL type

## Enumeration Type Documentation

## ◆ snd_ctl_elem_iface_t

enum snd_ctl_elem_iface_t

CTL related interface

Enumerator
SND_CTL_ELEM_IFACE_CARD | Card level
SND_CTL_ELEM_IFACE_HWDEP | Hardware dependent device
SND_CTL_ELEM_IFACE_MIXER | Mixer
SND_CTL_ELEM_IFACE_PCM | PCM
SND_CTL_ELEM_IFACE_RAWMIDI | RawMidi
SND_CTL_ELEM_IFACE_TIMER | Timer
SND_CTL_ELEM_IFACE_SEQUENCER | Sequencer

## ◆ snd_ctl_elem_type_t

enum snd_ctl_elem_type_t

CTL element type

Enumerator
SND_CTL_ELEM_TYPE_NONE | Invalid type
SND_CTL_ELEM_TYPE_BOOLEAN | Boolean contents
SND_CTL_ELEM_TYPE_INTEGER | Integer contents
SND_CTL_ELEM_TYPE_ENUMERATED | Enumerated contents
SND_CTL_ELEM_TYPE_BYTES | Bytes contents
SND_CTL_ELEM_TYPE_IEC958 | IEC958 (S/PDIF) setting content
SND_CTL_ELEM_TYPE_INTEGER64 | 64-bit integer contents

## ◆ snd_ctl_event_type_t

enum snd_ctl_event_type_t

Event class

Enumerator
SND_CTL_EVENT_ELEM | Elements related event

## ◆ snd_ctl_type_t

enum snd_ctl_type_t

CTL type

Enumerator
SND_CTL_TYPE_HW | Kernel level CTL
SND_CTL_TYPE_SHM | Shared memory client CTL
SND_CTL_TYPE_INET | INET client CTL (not yet implemented)
SND_CTL_TYPE_EXT | External control plugin
SND_CTL_TYPE_REMAP | Control functionality remapping

## Function Documentation

## ◆ snd_async_add_ctl_handler()

int snd_async_add_ctl_handler | ( | snd_async_handler_t ** | handler,
|  | snd_ctl_t * | ctl,
|  | snd_async_callback_t | callback,
|  | void * | private_data )

Add an async handler for a CTL.

Parameters

  handler | Returned handler handle
  ctl | CTL handle
  callback | Callback function
  private_data | Callback private data

Returns
  0 otherwise a negative error code on failure

## ◆ snd_async_handler_get_ctl()

snd_ctl_t * snd_async_handler_get_ctl | ( | snd_async_handler_t * | handler | ) |

Return CTL handle related to an async handler.

Parameters

  handler | Async handler handle

Returns
  CTL handle

## ◆ snd_card_get_index()

int snd_card_get_index | ( | const char * | string | ) |

Convert a card string to the card index.

This works only for physical sound cards, not for virtual cards.

Parameters

  string | A string identifying the card.

Returns
  The index of the card. On error, a a negative error code is returned.

The accepted formats for "string" are:

- The index of the card (as listed in /proc/asound/cards), given as string
- The ID of the card (as listed in /proc/asound/cards)
- The control device name (like /dev/snd/controlC0)

## ◆ snd_card_get_longname()

int snd_card_get_longname | ( | int | card,
|  | char ** | name )

Obtain the card long name.

Parameters

  card | Index of the card.
  name | Result - card long name corresponding to card index.

Returns
  Zero if success, otherwise a negative error code.

The value returned in name is allocated with strdup and should be freed when no longer used.

## ◆ snd_card_get_name()

int snd_card_get_name | ( | int | card,
|  | char ** | name )

Obtain the card name.

Parameters

  card | The index of the card.
  name | Result - card name corresponding to card index.

Returns
  zero if success, otherwise a negative error code

The value returned in name is allocated with strdup and should be freed when no longer used.

## ◆ snd_card_load()

int snd_card_load | ( | int | card | ) |

Try to load the driver for a card.

Parameters

  card | Card index.

Returns
  1 if driver is present, zero if driver is not present.

## ◆ snd_card_next()

int snd_card_next | ( | int * | rcard | ) |

Iterate over physical sound cards.

This function takes the index of a physical sound card and sets it to the index of the next card. If index is -1, it is set to the index of the first card. After the last card, the index is set to -1.

For example, if you have 2 sound cards (with index 0 and 1), the index will be modified as follows:

- -1 --> 0
- 0 --> 1
- 1 --> -1

This does not work for virtual sound cards.

Parameters

  rcard | Index of current card. The index of the next card is stored here.

Returns
  zero if success, otherwise a negative error code.

## ◆ snd_ctl_add_boolean_elem_set()

int snd_ctl_add_boolean_elem_set | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info,
|  | unsigned int | element_count,
|  | unsigned int | member_count )

Create and add some user-defined control elements of boolean type.

Parameters

  ctl | A handle of backend module for control interface.
  info | Common information for a new element set, with ID of the first new element.
  element_count | The number of elements added by this operation.
  member_count | The number of members which a element has to represent its states.

This function creates some user elements with boolean type. These elements are not controlled by device drivers in kernel. They can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify new control elements. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

All of members in the new elements are locked. The value of each member is initialized with false.

Errors:
  -EBUSY
    A element with ID id already exists.
  -EINVAL
    Some parameters include invalid value; i.e. ID has no name, or the number of members is not between 1 to 127.
  -ENOMEM
    Out of memory, or there are too many user elements.
  -ENXIO
    This backend module does not support user elements of boolean type.
  -ENODEV
    Device unplugged.

Compatibility:
  This function is added in version 1.1.2.

## ◆ snd_ctl_add_bytes_elem_set()

int snd_ctl_add_bytes_elem_set | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info,
|  | unsigned int | element_count,
|  | unsigned int | member_count )

Create and add some user-defined control elements of bytes type.

Parameters

  ctl | A handle of backend module for control interface.
  info | Common information for a new element set, with ID of the first new element.
  element_count | The number of elements added by this operation.
  member_count | The number of members which a element has to represent its states.

Returns
  Zero on success, otherwise a negative error code.

This function creates some user elements with bytes type. These elements are not controlled by device drivers in kernel. They can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify new control elements. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

All of members in the new elements are locked. The value of each member is initialized with the minimum value.

Errors:
  -EBUSY
    A element with ID id already exists.
  -EINVAL
    Some arguments include invalid value; i.e. ID has no name, or the number of members is not between 1 to 511.
  -ENOMEM
    Out of memory, or there are too many user elements.
  -ENXIO
    This backend module does not support user elements of bytes type.
  -ENODEV
    Device unplugged.

Compatibility:
  This function is added in version 1.1.2.

## ◆ snd_ctl_add_enumerated_elem_set()

int snd_ctl_add_enumerated_elem_set | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info,
|  | unsigned int | element_count,
|  | unsigned int | member_count,
|  | unsigned int | items,
|  | const char *const | labels[] )

Create and add some user-defined control elements of enumerated type.

Parameters

  ctl | A handle of backend module for control interface.
  info | Common information for a new element set, with ID of the first new element.
  element_count | The number of elements added by this operation.
  member_count | The number of members which a element has to represent its states.
  items | Range of possible values (0 ... items - 1).
  labels | An array containing items strings.

Returns
  Zero on success, otherwise a negative error code.

This function creates some user elements with enumerated type. These elements are not controlled by device drivers in kernel. They can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify new control elements. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

All of members in the new elements are locked. The value of each member is initialized with the first entry of labels.

Errors:
  -EBUSY
    A control element with ID id already exists.
  -EINVAL
    Some arguments include invalid value; i.e. element_count is not between 1 to 127, or items is not at least one, or a string in labels is empty, or longer than 63 bytes, or total length of the labels requires more than 64 KiB storage.
  -ENOMEM
    Out of memory, or there are too many user control elements.
  -ENXIO
    This driver does not support (enumerated) user controls.
  -ENODEV
    Device unplugged.

Compatibility:
  This function is added in version 1.1.2.

## ◆ snd_ctl_add_integer64_elem_set()

int snd_ctl_add_integer64_elem_set | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info,
|  | unsigned int | element_count,
|  | unsigned int | member_count,
|  | long long | min,
|  | long long | max,
|  | long long | step )

Create and add some user-defined control elements of integer64 type.

Parameters

  ctl | A handle of backend module for control interface.
  info | Common information for a new element set, with ID of the first new element.
  element_count | The number of elements added by this operation.
  member_count | The number of members which a element has to represent its states.
  min | Minimum value for each member of the elements.
  max | Maximum value for each member of the elements.
  step | The step of value for each member in the elements.

Returns
  Zero on success, otherwise a negative error code.

This function creates some user elements with integer64 type. These elements are not controlled by device drivers in kernel. They can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify new control elements. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

All of members in the new elements are locked. The value of each member is initialized with the minimum value.

Errors:
  -EBUSY
    A element with ID id already exists.
  -EINVAL
    Some arguments include invalid value; i.e. ID has no name, or the number of members is not between 1 to 127.
  -ENOMEM
    Out of memory, or there are too many user elements.
  -ENXIO
    This backend module does not support user elements of integer64 type.
  -ENODEV
    Device unplugged.

Compatibility:
  This function is added in version 1.1.2.

## ◆ snd_ctl_add_integer_elem_set()

int snd_ctl_add_integer_elem_set | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info,
|  | unsigned int | element_count,
|  | unsigned int | member_count,
|  | long | min,
|  | long | max,
|  | long | step )

Create and add some user-defined control elements of integer type.

Parameters

  ctl | A handle of backend module for control interface.
  info | Common information for a new element set, with ID of the first new element.
  element_count | The number of elements added by this operation.
  member_count | The number of members which a element has to represent its states.
  min | Minimum value for each member of the elements.
  max | Maximum value for each member of the elements.
  step | The step of value for each member in the elements.

Returns
  Zero on success, otherwise a negative error code.

This function creates some user elements with integer type. These elements are not controlled by device drivers in kernel. They can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify new control elements. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

All of members in the new elements are locked. The value of each member is initialized with the minimum value.

Errors:
  -EBUSY
    A element with ID id already exists.
  -EINVAL
    Some arguments include invalid value; i.e. ID field in info has no name, or the number of members is not between 1 to 127.
  -ENOMEM
    Out of memory, or there are too many user elements.
  -ENXIO
    This backend module does not support user elements of integer type.
  -ENODEV
    Device unplugged.

Compatibility:
  This function is added in version 1.1.2.

## ◆ snd_ctl_ascii_elem_id_get()

char * snd_ctl_ascii_elem_id_get | ( | snd_ctl_elem_id_t * | id | ) |

return ASCII CTL element identifier name

Parameters

  id | CTL identifier

Returns
  ascii identifier of CTL element

The string is allocated using strdup().

## ◆ snd_ctl_ascii_elem_id_parse()

int snd_ctl_ascii_elem_id_parse | ( | snd_ctl_elem_id_t * | dst,
|  | const char * | str )

parse ASCII string as CTL element identifier

Parameters

  dst | destination CTL identifier
  str | source ASCII string

Returns
  zero on success, otherwise a negative error code

## ◆ snd_ctl_ascii_value_parse()

int snd_ctl_ascii_value_parse | ( | snd_ctl_t * | handle,
|  | snd_ctl_elem_value_t * | dst,
|  | snd_ctl_elem_info_t * | info,
|  | const char * | value )

parse ASCII string as CTL element value

Parameters

  handle | CTL handle
  dst | destination CTL element value
  info | CTL element info structure
  value | source ASCII string

Returns
  zero on success, otherwise a negative error code

Note: For toggle command, the dst must contain previous (current) state (do the snd_ctl_elem_read call to obtain it).

## ◆ snd_ctl_card_info()

int snd_ctl_card_info | ( | snd_ctl_t * | ctl,
|  | snd_ctl_card_info_t * | info )

Get information about the sound card.

Obtain information about the sound card previously opened using snd_ctl_open(). The object "info" must be allocated prior to calling this function. See snd_ctl_card_info_t for details.

Parameters

  ctl | The CTL handle.
  info | The card information is stored here.

Returns
  0 on success, otherwise a negative error code.

## ◆ snd_ctl_card_info_clear()

void snd_ctl_card_info_clear | ( | snd_ctl_card_info_t * | obj | ) |

Clear given card info object.

See snd_ctl_elem_value_t for details.

Parameters

  obj | Card info object.

## ◆ snd_ctl_card_info_copy()

void snd_ctl_card_info_copy | ( | snd_ctl_card_info_t * | dst,
|  | const snd_ctl_card_info_t * | src )

Bitwise copy of a snd_ctl_card_info_t object.

Parameters

  dst | Pointer to destination.
  src | Pointer to source.

## ◆ snd_ctl_card_info_free()

void snd_ctl_card_info_free | ( | snd_ctl_card_info_t * | obj | ) |

Free an snd_ctl_card_info_t previously allocated using snd_ctl_card_info_malloc().

Parameters

  obj | Pointer to the snd_ctl_card_info_t.

## ◆ snd_ctl_card_info_get_card()

int snd_ctl_card_info_get_card | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound card index from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound card index.

## ◆ snd_ctl_card_info_get_components()

const char * snd_ctl_card_info_get_components | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound cards "components" property from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound cards "components" property.

## ◆ snd_ctl_card_info_get_driver()

const char * snd_ctl_card_info_get_driver | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound card driver from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  The sound card driver.

## ◆ snd_ctl_card_info_get_id()

const char * snd_ctl_card_info_get_id | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound card ID from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound card ID.

## ◆ snd_ctl_card_info_get_longname()

const char * snd_ctl_card_info_get_longname | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound cards long name from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound cards long name.

## ◆ snd_ctl_card_info_get_mixername()

const char * snd_ctl_card_info_get_mixername | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound card mixer name from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound card mixer name.

## ◆ snd_ctl_card_info_get_name()

const char * snd_ctl_card_info_get_name | ( | const snd_ctl_card_info_t * | obj | ) |

Get the sound card name from the given info object.

See snd_ctl_card_info_t for more details.

Parameters

  obj | The card info object.

Returns
  Sound card name.

## ◆ snd_ctl_card_info_malloc()

int snd_ctl_card_info_malloc | ( | snd_ctl_card_info_t ** | ptr | ) |

Allocate an invalid snd_ctl_card_info_t on the heap.

Allocate space for a card info object on the heap. The allocated memory must be freed using snd_ctl_card_info_free().

See snd_ctl_card_info_t for details.

Parameters

  ptr | Pointer to a snd_ctl_card_info_t pointer. The address of the allocated space will be returned here.

Returns
  0 on success, otherwise a negative error code.

## ◆ snd_ctl_card_info_sizeof()

size_t snd_ctl_card_info_sizeof | ( | void |  | ) |

get size of snd_ctl_card_info_t.

Returns
  Size in bytes.

## ◆ snd_ctl_close()

int snd_ctl_close | ( | snd_ctl_t * | ctl | ) |

close CTL handle

Parameters

  ctl | CTL handle

Returns
  0 on success otherwise a negative error code

Closes the specified CTL handle and frees all associated resources.

## ◆ snd_ctl_convert_from_dB()

int snd_ctl_convert_from_dB | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | long | db_gain,
|  | long * | value,
|  | int | xdir )

Convert from dB gain to the raw volume value on the given control element.

Parameters

  ctl | the control handler
  id | the element id
  db_gain | the dB gain to convert (in 0.01dB unit)
  value | the pointer to store the converted raw volume value
  xdir | the direction for round-up. The value is round up when this is positive.

Returns
  0 if successful, or a negative error code

## ◆ snd_ctl_convert_to_dB()

int snd_ctl_convert_to_dB | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | long | volume,
|  | long * | db_gain )

Convert the volume value to dB on the given control element.

Parameters

  ctl | the control handler
  id | the element id
  volume | the raw volume value to convert
  db_gain | the dB gain (in 0.01dB unit)

Returns
  0 if successful, or a negative error code

## ◆ snd_ctl_elem_add_boolean()

int snd_ctl_elem_add_boolean | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | unsigned int | member_count )

Create and add an user-defined control element of boolean type.

This is a wrapper function to snd_ctl_add_boolean_elem_set() for a single control element. This doesn't fill the id data with full information, thus it's recommended to use snd_ctl_add_boolean_elem_set(), instead.

## ◆ snd_ctl_elem_add_enumerated()

int snd_ctl_elem_add_enumerated | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | unsigned int | member_count,
|  | unsigned int | items,
|  | const char *const | labels[] )

Create and add a user-defined control element of enumerated type.

This is a wrapper function to snd_ctl_add_enumerated_elem_set() for a single control element. This doesn't fill the id data with full information, thus it's recommended to use snd_ctl_add_enumerated_elem_set(), instead.

This function is added in version 1.0.25.

## ◆ snd_ctl_elem_add_iec958()

int snd_ctl_elem_add_iec958 | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id )

Create and add a user-defined control element of IEC958 type.

Parameters

  [in] | ctl | A handle of backend module for control interface.
  [in,out] | id | ID of the new control element.

This function creates an user element with IEC958 type. This element is not controlled by device drivers in kernel. It can be operated by the same way as usual elements added by the device drivers.

The name field of id must be set with unique value to identify a new control element. After returning, all fields of id are filled. A element can be identified by the combination of name and index, or by numid.

A member in the new element is locked and filled with zero.

Errors:
  -EBUSY
    A control element with ID id already exists.
  -EINVAL
    ID has no name.
  -ENOMEM
    Out of memory, or there are too many user elements.
  -ENXIO
    This backend module does not support user elements of IEC958 type.
  -ENODEV
    Device unplugged.

## ◆ snd_ctl_elem_add_integer()

int snd_ctl_elem_add_integer | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | unsigned int | member_count,
|  | long | min,
|  | long | max,
|  | long | step )

Create and add an user-defined control element of integer type.

This is a wrapper function to snd_ctl_add_integer_elem_set() for a control element. This doesn't fill the id data with full information, thus it's recommended to use snd_ctl_add_integer_elem_set(), instead.

## ◆ snd_ctl_elem_add_integer64()

int snd_ctl_elem_add_integer64 | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | unsigned int | member_count,
|  | long long | min,
|  | long long | max,
|  | long long | step )

Create and add an user-defined control element of integer64 type.

This is a wrapper function to snd_ctl_add_integer64_elem_set() for a single control element. This doesn't fill the id data with full information, thus it's recommended to use snd_ctl_add_integer64_elem_set(), instead.

## ◆ snd_ctl_elem_id_clear()

void snd_ctl_elem_id_clear | ( | snd_ctl_elem_id_t * | obj | ) |

clear given snd_ctl_elem_id_t object

Parameters

  obj | pointer to object to clear

## ◆ snd_ctl_elem_id_compare_numid()

int snd_ctl_elem_id_compare_numid | ( | const snd_ctl_elem_id_t * | id1,
|  | const snd_ctl_elem_id_t * | id2 )

compare one snd_ctl_elem_id_t to another using numid

Parameters

  id1 | pointer to first id
  id2 | pointer to second id

Return values

  zero | when values are identical, other value on a difference (like strcmp)

This comparison ignores the set of fields part.

The return value can be used for sorting like qsort(). It gives persistent results.

## ◆ snd_ctl_elem_id_compare_set()

int snd_ctl_elem_id_compare_set | ( | const snd_ctl_elem_id_t * | id1,
|  | const snd_ctl_elem_id_t * | id2 )

compare one snd_ctl_elem_id_t to another

Parameters

  id1 | pointer to first id
  id2 | pointer to second id

Return values

  zero | when values are identical, other value on a difference (like strcmp)

This comparison ignores the numid part. The numid comparison can be easily implemented using snd_ctl_elem_id_get_numid() calls.

The identifier set fields are compared in this order: interface, device, subdevice, name, index.

The return value can be used for sorting like qsort(). It gives persistent results.

## ◆ snd_ctl_elem_id_copy()

void snd_ctl_elem_id_copy | ( | snd_ctl_elem_id_t * | dst,
|  | const snd_ctl_elem_id_t * | src )

copy one snd_ctl_elem_id_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

## ◆ snd_ctl_elem_id_free()

void snd_ctl_elem_id_free | ( | snd_ctl_elem_id_t * | obj | ) |

frees a previously allocated snd_ctl_elem_id_t

Parameters

  obj | pointer to object to free

## ◆ snd_ctl_elem_id_get_device()

unsigned int snd_ctl_elem_id_get_device | ( | const snd_ctl_elem_id_t * | obj | ) |

Get device part of a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element related device

## ◆ snd_ctl_elem_id_get_index()

unsigned int snd_ctl_elem_id_get_index | ( | const snd_ctl_elem_id_t * | obj | ) |

Get index part of a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element index

## ◆ snd_ctl_elem_id_get_interface()

snd_ctl_elem_iface_t snd_ctl_elem_id_get_interface | ( | const snd_ctl_elem_id_t * | obj | ) |

Get interface part of a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element related interface

## ◆ snd_ctl_elem_id_get_name()

const char * snd_ctl_elem_id_get_name | ( | const snd_ctl_elem_id_t * | obj | ) |

Get name part of a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element name

## ◆ snd_ctl_elem_id_get_numid()

unsigned int snd_ctl_elem_id_get_numid | ( | const snd_ctl_elem_id_t * | obj | ) |

Get numeric identifier from a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element numeric identifier

## ◆ snd_ctl_elem_id_get_subdevice()

unsigned int snd_ctl_elem_id_get_subdevice | ( | const snd_ctl_elem_id_t * | obj | ) |

Get subdevice part of a CTL element identifier.

Parameters

  obj | CTL element identifier

Returns
  CTL element related subdevice

## ◆ snd_ctl_elem_id_malloc()

int snd_ctl_elem_id_malloc | ( | snd_ctl_elem_id_t ** | ptr | ) |

allocate an invalid snd_ctl_elem_id_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

## ◆ snd_ctl_elem_id_set_device()

void snd_ctl_elem_id_set_device | ( | snd_ctl_elem_id_t * | obj,
|  | unsigned int | val )

Set device part for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element related device

## ◆ snd_ctl_elem_id_set_index()

void snd_ctl_elem_id_set_index | ( | snd_ctl_elem_id_t * | obj,
|  | unsigned int | val )

Set index part for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element index

## ◆ snd_ctl_elem_id_set_interface()

void snd_ctl_elem_id_set_interface | ( | snd_ctl_elem_id_t * | obj,
|  | snd_ctl_elem_iface_t | val )

Set interface part for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element related interface

## ◆ snd_ctl_elem_id_set_name()

void snd_ctl_elem_id_set_name | ( | snd_ctl_elem_id_t * | obj,
|  | const char * | val )

Set name part for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element name

## ◆ snd_ctl_elem_id_set_numid()

void snd_ctl_elem_id_set_numid | ( | snd_ctl_elem_id_t * | obj,
|  | unsigned int | val )

Set numeric identifier for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element numeric identifier

## ◆ snd_ctl_elem_id_set_subdevice()

void snd_ctl_elem_id_set_subdevice | ( | snd_ctl_elem_id_t * | obj,
|  | unsigned int | val )

Set subdevice part for a CTL element identifier.

Parameters

  obj | CTL element identifier
  val | CTL element related subdevice

## ◆ snd_ctl_elem_id_sizeof()

size_t snd_ctl_elem_id_sizeof | ( | void |  | ) |

get size of snd_ctl_elem_id_t

Returns
  size in bytes

## ◆ snd_ctl_elem_iface_name()

const char * snd_ctl_elem_iface_name | ( | snd_ctl_elem_iface_t | iface | ) |

get name of a CTL element related interface

Parameters

  iface | CTL element related interface

Returns
  ascii name of CTL element related interface

## ◆ snd_ctl_elem_info()

int snd_ctl_elem_info | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_info_t * | info )

Get CTL element information.

Parameters

  ctl | CTL handle
  info | CTL element id/information pointer

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_elem_info_clear()

void snd_ctl_elem_info_clear | ( | snd_ctl_elem_info_t * | obj | ) |

clear given snd_ctl_elem_info_t object

Parameters

  obj | pointer to object to clear

## ◆ snd_ctl_elem_info_copy()

void snd_ctl_elem_info_copy | ( | snd_ctl_elem_info_t * | dst,
|  | const snd_ctl_elem_info_t * | src )

copy one snd_ctl_elem_info_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

## ◆ snd_ctl_elem_info_free()

void snd_ctl_elem_info_free | ( | snd_ctl_elem_info_t * | obj | ) |

frees a previously allocated snd_ctl_elem_info_t

Parameters

  obj | pointer to object to free

## ◆ snd_ctl_elem_info_get_count()

unsigned int snd_ctl_elem_info_get_count | ( | const snd_ctl_elem_info_t * | obj | ) |

Get number of value entries from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  value entries count

## ◆ snd_ctl_elem_info_get_device()

unsigned int snd_ctl_elem_info_get_device | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  device part of element identifier

## ◆ snd_ctl_elem_info_get_dimension()

int snd_ctl_elem_info_get_dimension | ( | const snd_ctl_elem_info_t * | obj,
|  | unsigned int | idx )

Get specified of dimension width for given element.

Parameters

  obj | CTL element id/info
  idx | The dimension index

Returns
  zero value if no dimension width is defined, otherwise positive value with with of specified dimension

Deprecated
  Since 1.1.5 snd_ctl_elem_info_get_dimension is deprecated without any replacement.

## ◆ snd_ctl_elem_info_get_dimensions()

int snd_ctl_elem_info_get_dimensions | ( | const snd_ctl_elem_info_t * | obj | ) |

Get count of dimensions for given element.

Parameters

  obj | CTL element id/info

Returns
  zero value if no dimensions are defined, otherwise positive value with count of dimensions

Deprecated
  Since 1.1.5 snd_ctl_elem_info_get_dimensions is deprecated without any replacement.

## ◆ snd_ctl_elem_info_get_id()

void snd_ctl_elem_info_get_id | ( | const snd_ctl_elem_info_t * | obj,
|  | snd_ctl_elem_id_t * | ptr )

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

Parameters

  obj | CTL element id/info
  ptr | Pointer to returned CTL element identifier

## ◆ snd_ctl_elem_info_get_index()

unsigned int snd_ctl_elem_info_get_index | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  index part of element identifier

## ◆ snd_ctl_elem_info_get_interface()

snd_ctl_elem_iface_t snd_ctl_elem_info_get_interface | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  interface part of element identifier

## ◆ snd_ctl_elem_info_get_item_name()

const char * snd_ctl_elem_info_get_item_name | ( | const snd_ctl_elem_info_t * | obj | ) |

Get name for selected item in a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  name of chosen item

## ◆ snd_ctl_elem_info_get_items()

unsigned int snd_ctl_elem_info_get_items | ( | const snd_ctl_elem_info_t * | obj | ) |

Get number of items available from a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  items count

## ◆ snd_ctl_elem_info_get_max()

long snd_ctl_elem_info_get_max | ( | const snd_ctl_elem_info_t * | obj | ) |

Get maximum value from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Maximum value

## ◆ snd_ctl_elem_info_get_max64()

long long snd_ctl_elem_info_get_max64 | ( | const snd_ctl_elem_info_t * | obj | ) |

Get maximum value from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Maximum value

## ◆ snd_ctl_elem_info_get_min()

long snd_ctl_elem_info_get_min | ( | const snd_ctl_elem_info_t * | obj | ) |

Get minimum value from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Minimum value

## ◆ snd_ctl_elem_info_get_min64()

long long snd_ctl_elem_info_get_min64 | ( | const snd_ctl_elem_info_t * | obj | ) |

Get minimum value from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Minimum value

## ◆ snd_ctl_elem_info_get_name()

const char * snd_ctl_elem_info_get_name | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  name part of element identifier

## ◆ snd_ctl_elem_info_get_numid()

unsigned int snd_ctl_elem_info_get_numid | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  element numeric identifier

## ◆ snd_ctl_elem_info_get_owner()

pid_t snd_ctl_elem_info_get_owner | ( | const snd_ctl_elem_info_t * | obj | ) |

Get owner of a locked element.

Parameters

  obj | CTL element id/info

Returns
  value entries count

## ◆ snd_ctl_elem_info_get_step()

long snd_ctl_elem_info_get_step | ( | const snd_ctl_elem_info_t * | obj | ) |

Get value step from a SND_CTL_ELEM_TYPE_INTEGER CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Step

## ◆ snd_ctl_elem_info_get_step64()

long long snd_ctl_elem_info_get_step64 | ( | const snd_ctl_elem_info_t * | obj | ) |

Get value step from a SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  Step

## ◆ snd_ctl_elem_info_get_subdevice()

unsigned int snd_ctl_elem_info_get_subdevice | ( | const snd_ctl_elem_info_t * | obj | ) |

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

Parameters

  obj | CTL element id/info

Returns
  subdevice part of element identifier

## ◆ snd_ctl_elem_info_get_type()

snd_ctl_elem_type_t snd_ctl_elem_info_get_type | ( | const snd_ctl_elem_info_t * | obj | ) |

Get type from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  CTL element content type

## ◆ snd_ctl_elem_info_is_inactive()

int snd_ctl_elem_info_is_inactive | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about status from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element value is not active, 1 if is active

## ◆ snd_ctl_elem_info_is_locked()

int snd_ctl_elem_info_is_locked | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info whether an element is locked.

Parameters

  obj | CTL element id/info

Returns
  0 if element value is currently changeable, 1 if it's locked by another application

## ◆ snd_ctl_elem_info_is_owner()

int snd_ctl_elem_info_is_owner | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info if I own an element.

Parameters

  obj | CTL element id/info

Returns
  0 if element value is currently changeable, 1 if it's locked by another application

## ◆ snd_ctl_elem_info_is_readable()

int snd_ctl_elem_info_is_readable | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about readability from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element is not readable, 1 if element is readable

## ◆ snd_ctl_elem_info_is_tlv_commandable()

int snd_ctl_elem_info_is_tlv_commandable | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about TLV command possibility from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element's TLV command is not possible, 1 if element's TLV command is supported

## ◆ snd_ctl_elem_info_is_tlv_readable()

int snd_ctl_elem_info_is_tlv_readable | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about TLV readability from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element's TLV is not readable, 1 if element's TLV is readable

## ◆ snd_ctl_elem_info_is_tlv_writable()

int snd_ctl_elem_info_is_tlv_writable | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about TLV writeability from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element's TLV is not writable, 1 if element's TLV is writable

## ◆ snd_ctl_elem_info_is_user()

int snd_ctl_elem_info_is_user | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info if it's a user element.

Parameters

  obj | CTL element id/info

Returns
  0 if element value is a system element, 1 if it's a user-created element

## ◆ snd_ctl_elem_info_is_volatile()

int snd_ctl_elem_info_is_volatile | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about notification feasibility from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if all element value changes are notified to subscribed applications, 1 otherwise

## ◆ snd_ctl_elem_info_is_writable()

int snd_ctl_elem_info_is_writable | ( | const snd_ctl_elem_info_t * | obj | ) |

Get info about writability from a CTL element id/info.

Parameters

  obj | CTL element id/info

Returns
  0 if element is not writable, 1 if element is not writable

## ◆ snd_ctl_elem_info_malloc()

int snd_ctl_elem_info_malloc | ( | snd_ctl_elem_info_t ** | ptr | ) |

allocate an invalid snd_ctl_elem_info_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

## ◆ snd_ctl_elem_info_set_device()

void snd_ctl_elem_info_set_device | ( | snd_ctl_elem_info_t * | obj,
|  | unsigned int | val )

Set device part of CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | device part of element identifier

## ◆ snd_ctl_elem_info_set_dimension()

int snd_ctl_elem_info_set_dimension | ( | snd_ctl_elem_info_t * | info,
|  | const int | dimension[4] )

Set width to a specified dimension level of given element information.

Parameters

  info | Information of an element.
  dimension | Dimension width for each level by member unit.

Returns
  Zero on success, otherwise a negative error code.

Errors:
  -EINVAL
    Invalid arguments are given as parameters.

Compatibility:
  This function is added in version 1.1.2.

Deprecated
  Since 1.1.5 snd_ctl_elem_info_set_dimension is deprecated without any replacement.

## ◆ snd_ctl_elem_info_set_id()

void snd_ctl_elem_info_set_id | ( | snd_ctl_elem_info_t * | obj,
|  | const snd_ctl_elem_id_t * | ptr )

Set CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  ptr | CTL element identifier

## ◆ snd_ctl_elem_info_set_inactive()

void snd_ctl_elem_info_set_inactive | ( | snd_ctl_elem_info_t * | obj,
|  | int | val )

Set inactive parameter of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | inactive part of element identifier

## ◆ snd_ctl_elem_info_set_index()

void snd_ctl_elem_info_set_index | ( | snd_ctl_elem_info_t * | obj,
|  | unsigned int | val )

Set index part of CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | index part of element identifier

## ◆ snd_ctl_elem_info_set_interface()

void snd_ctl_elem_info_set_interface | ( | snd_ctl_elem_info_t * | obj,
|  | snd_ctl_elem_iface_t | val )

Set interface part of CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | interface part of element identifier

## ◆ snd_ctl_elem_info_set_item()

void snd_ctl_elem_info_set_item | ( | snd_ctl_elem_info_t * | obj,
|  | unsigned int | val )

Select item in a SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info.

Parameters

  obj | CTL element id/info
  val | item number

## ◆ snd_ctl_elem_info_set_name()

void snd_ctl_elem_info_set_name | ( | snd_ctl_elem_info_t * | obj,
|  | const char * | val )

Set name part of CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | name part of element identifier

## ◆ snd_ctl_elem_info_set_numid()

void snd_ctl_elem_info_set_numid | ( | snd_ctl_elem_info_t * | obj,
|  | unsigned int | val )

Set element numeric identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | element numeric identifier

## ◆ snd_ctl_elem_info_set_read_write()

void snd_ctl_elem_info_set_read_write | ( | snd_ctl_elem_info_t * | obj,
|  | int | rval,
|  | int | wval )

Set readability/writeability parameter of a CTL element id/info.

Parameters

  obj | CTL element id/info
  rval | readability part of element identifier
  wval | writeability part of element identifier

## ◆ snd_ctl_elem_info_set_subdevice()

void snd_ctl_elem_info_set_subdevice | ( | snd_ctl_elem_info_t * | obj,
|  | unsigned int | val )

Set subdevice part of CTL element identifier of a CTL element id/info.

Parameters

  obj | CTL element id/info
  val | subdevice part of element identifier

## ◆ snd_ctl_elem_info_set_tlv_read_write()

void snd_ctl_elem_info_set_tlv_read_write | ( | snd_ctl_elem_info_t * | obj,
|  | int | rval,
|  | int | wval )

Set TLV readability/writeability parameter of a CTL element id/info.

Parameters

  obj | CTL element id/info
  rval | TLV readability part of element identifier
  wval | TLV writeability part of element identifier

## ◆ snd_ctl_elem_info_sizeof()

size_t snd_ctl_elem_info_sizeof | ( | void |  | ) |

get size of snd_ctl_elem_info_t

Returns
  size in bytes

## ◆ snd_ctl_elem_list()

int snd_ctl_elem_list | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_list_t * | list )

Get a list of element identifiers.

Before calling this function, memoru must be allocated using snd_ctl_elem_list_malloc().

This function obtains data from the sound card driver and puts it into the list.

If there was space allocated for the element identifiers (using snd_ctl_elem_list_alloc_space()), information will be filled in. If too little space was allocated, only a part of the elements will be queried. If there was too much space allocated, some of it remains unused. Use snd_ctl_elem_list_get_count() and snd_ctl_elem_list_get_used() to obtain information about space usage. See snd_ctl_elem_list_t to learn more.

Parameters

  ctl | CTL handle
  list | CTL element identifiers list pointer

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_elem_list_alloc_space()

int snd_ctl_elem_list_alloc_space | ( | snd_ctl_elem_list_t * | obj,
|  | unsigned int | entries )

allocate space for CTL element identifiers list

The space can be released with snd_ctl_elem_list_free_space().

Parameters

  obj | CTL element identifiers list.
  entries | How many entries to allocate. See snd_ctl_elem_list_t to learn how to obtain this number in advance.

Returns
  0 on success otherwise a negative error code.

## ◆ snd_ctl_elem_list_clear()

void snd_ctl_elem_list_clear | ( | snd_ctl_elem_list_t * | obj | ) |

Clear given snd_ctl_elem_list_t object.

This will make the stored identifiers inaccessible without freeing their space.

Warning
  The element identifier space cannot be freed after calling this function. Therefore, snd_ctl_elem_list_free_space() must be called in advance.

Parameters

  obj | pointer to object to clear

## ◆ snd_ctl_elem_list_copy()

void snd_ctl_elem_list_copy | ( | snd_ctl_elem_list_t * | dst,
|  | const snd_ctl_elem_list_t * | src )

copy one snd_ctl_elem_list_t to another.

This performs a shallow copy. That means the both lists will share the same space for the elements. The elements will not be copied.

Parameters

  dst | pointer to destination
  src | pointer to source

## ◆ snd_ctl_elem_list_free()

void snd_ctl_elem_list_free | ( | snd_ctl_elem_list_t * | obj | ) |

frees a previously allocated snd_ctl_elem_list_t.

Release memory previously allocated using snd_ctl_elem_list_malloc().

If you used snd_ctl_elem_list_alloc_space() on the list, you must use snd_ctl_elem_list_free_space() before calling this function.

Parameters

  obj | pointer to object to free

## ◆ snd_ctl_elem_list_free_space()

void snd_ctl_elem_list_free_space | ( | snd_ctl_elem_list_t * | obj | ) |

free previously allocated space for CTL element identifiers list

Releases space previously allocated using snd_ctl_elem_list_alloc_space().

Parameters

  obj | CTL element identifiers list

## ◆ snd_ctl_elem_list_get_count()

unsigned int snd_ctl_elem_list_get_count | ( | const snd_ctl_elem_list_t * | obj | ) |

Get total count of elements present in CTL device.

This function returns how many entries were allocated using snd_ctl_elem_list_alloc_space(). This information is present after snd_ctl_elem_list() was called.

See also snd_ctl_elem_list_get_used().

Parameters

  obj | CTL element identifier list

Returns
  total number of elements

## ◆ snd_ctl_elem_list_get_device()

unsigned int snd_ctl_elem_list_get_device | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get the device part of CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element related device

## ◆ snd_ctl_elem_list_get_id()

void snd_ctl_elem_list_get_id | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx,
|  | snd_ctl_elem_id_t * | ptr )

Get CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry
  ptr | Pointer to returned CTL element identifier

## ◆ snd_ctl_elem_list_get_index()

unsigned int snd_ctl_elem_list_get_index | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get index part of CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element index

## ◆ snd_ctl_elem_list_get_interface()

snd_ctl_elem_iface_t snd_ctl_elem_list_get_interface | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get interface part of CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element related interface

## ◆ snd_ctl_elem_list_get_name()

const char * snd_ctl_elem_list_get_name | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get name part of CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element name

## ◆ snd_ctl_elem_list_get_numid()

unsigned int snd_ctl_elem_list_get_numid | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get CTL element numeric identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element numeric identifier

## ◆ snd_ctl_elem_list_get_subdevice()

unsigned int snd_ctl_elem_list_get_subdevice | ( | const snd_ctl_elem_list_t * | obj,
|  | unsigned int | idx )

Get subdevice part of CTL element identifier for an entry of a CTL element identifiers list.

Parameters

  obj | CTL element identifier list
  idx | Index of entry

Returns
  CTL element related subdevice

## ◆ snd_ctl_elem_list_get_used()

unsigned int snd_ctl_elem_list_get_used | ( | const snd_ctl_elem_list_t * | obj | ) |

Get number of used entries in CTL element identifiers list.

This function returns how many entries are actually filled with useful information.

See also snd_ctl_elem_list_get_count().

Parameters

  obj | CTL element identifier list

Returns
  number of used entries

## ◆ snd_ctl_elem_list_malloc()

int snd_ctl_elem_list_malloc | ( | snd_ctl_elem_list_t ** | ptr | ) |

allocate a snd_ctl_elem_list_t using standard malloc.

The memory can be released using snd_ctl_elem_list_free().

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

## ◆ snd_ctl_elem_list_set_offset()

void snd_ctl_elem_list_set_offset | ( | snd_ctl_elem_list_t * | obj,
|  | unsigned int | val )

Set index of first wanted CTL element identifier in a CTL element identifiers list.

Parameters

  obj | CTL element identifiers list
  val | index of CTL element to put at position 0 of list

## ◆ snd_ctl_elem_list_sizeof()

size_t snd_ctl_elem_list_sizeof | ( | void |  | ) |

get size of snd_ctl_elem_list_t.

Returns
  size in bytes

## ◆ snd_ctl_elem_lock()

int snd_ctl_elem_lock | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_id_t * | id )

Lock CTL element.

Parameters

  ctl | CTL handle
  id | CTL element id pointer

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_elem_read()

int snd_ctl_elem_read | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_value_t * | data )

Get CTL element value.

Read information from sound card. You must set the ID of the element before calling this function.

See snd_ctl_elem_value_t for details.

Parameters

  ctl | CTL handle.
  data | The element value. The ID must be set before calling the function, and the actual value will be returned here.

Returns
  0 on success otherwise a negative error code.

## ◆ snd_ctl_elem_remove()

int snd_ctl_elem_remove | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_id_t * | id )

Remove an user CTL element.

Parameters

  ctl | CTL handle
  id | CTL element identification

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_elem_set_bytes()

void snd_ctl_elem_set_bytes | ( | snd_ctl_elem_value_t * | obj,
|  | void * | data,
|  | size_t | size )

Replace the data stored within the element.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It replaces the data stored in the element. Note that "bytes" elements don't have members. They have only one single block of data.

See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  data | Pointer to the new data.
  size | The size of the new data, in bytes.

## ◆ snd_ctl_elem_tlv_command()

int snd_ctl_elem_tlv_command | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | const unsigned int * | tlv )

Process structured data from given buffer for an element set.

Parameters

  ctl | A handle of backend module for control interface.
  id | ID of an element.
  tlv | An array with members of unsigned int type. The second member must represent total bytes of the rest of array.

Return values

  0 | on success
  >0 | on success when value was changed
  <0 | a negative error code

The format of an array of tlv argument is: tlv[0]: Type. One of SND_CTL_TLVT_XXX. tlv[1]: Length. The length of value in units of byte. tlv[2..]: Value. Depending on the type.

Details are described in <sound/tlv.h>.

## ◆ snd_ctl_elem_tlv_read()

int snd_ctl_elem_tlv_read | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | unsigned int * | tlv,
|  | unsigned int | tlv_size )

Read structured data from an element set to given buffer.

Parameters

  ctl | A handle of backend module for control interface.
  id | ID of an element.
  tlv | An array with members of unsigned int type.
  tlv_size | The length of the array.

Returns
  0 on success otherwise a negative error code

The format of an array of tlv argument is: tlv[0]: Type. One of SND_CTL_TLVT_XXX. tlv[1]: Length. The length of value in units of byte. tlv[2..]: Value. Depending on the type.

Details are described in <sound/tlv.h>.

## ◆ snd_ctl_elem_tlv_write()

int snd_ctl_elem_tlv_write | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | const unsigned int * | tlv )

Write structured data from given buffer to an element set.

Parameters

  ctl | A handle of backend module for control interface.
  id | ID of an element.
  tlv | An array with members of unsigned int type. The second member must represent total bytes of the rest of array.

Return values

  0 | on success
  >0 | on success when value was changed
  <0 | a negative error code

The format of an array of tlv argument is: tlv[0]: Type. One of SND_CTL_TLVT_XXX. tlv[1]: Length. The length of value in units of byte. tlv[2..]: Value. Depending on the type.

Details are described in <sound/tlv.h>.

## ◆ snd_ctl_elem_type_name()

const char * snd_ctl_elem_type_name | ( | snd_ctl_elem_type_t | type | ) |

get name of a CTL element type

Parameters

  type | CTL element type

Returns
  ascii name of CTL element type

## ◆ snd_ctl_elem_unlock()

int snd_ctl_elem_unlock | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_id_t * | id )

Unlock CTL element.

Parameters

  ctl | CTL handle
  id | CTL element id pointer

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_elem_value_clear()

void snd_ctl_elem_value_clear | ( | snd_ctl_elem_value_t * | obj | ) |

Clear given data of an element.

See snd_ctl_elem_value_t for details.

Parameters

  obj | Data of an element.

## ◆ snd_ctl_elem_value_compare()

int snd_ctl_elem_value_compare | ( | snd_ctl_elem_value_t * | left,
|  | const snd_ctl_elem_value_t * | right )

Compare two snd_ctl_elem_value_t values, bytewise.

Parameters

  left | First value.
  right | Second value.

Returns
  0 on match, less than or greater than otherwise, see memcmp(3).

## ◆ snd_ctl_elem_value_copy()

void snd_ctl_elem_value_copy | ( | snd_ctl_elem_value_t * | dst,
|  | const snd_ctl_elem_value_t * | src )

Bitwise copy of a snd_ctl_elem_value_t value.

Parameters

  dst | Pointer to destination.
  src | Pointer to source.

## ◆ snd_ctl_elem_value_free()

void snd_ctl_elem_value_free | ( | snd_ctl_elem_value_t * | obj | ) |

Free an snd_ctl_elem_value_t previously allocated using snd_ctl_elem_value_malloc().

Parameters

  obj | Pointer to the snd_ctl_elem_value_t.

## ◆ snd_ctl_elem_value_get_boolean()

int snd_ctl_elem_value_get_boolean | ( | const snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx )

Get an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It returns the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object
  idx | The index of the member.

Returns
  The members value.

## ◆ snd_ctl_elem_value_get_byte()

unsigned char snd_ctl_elem_value_get_byte | ( | const snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx )

Get an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It returns the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.

Returns
  The members value.

## ◆ snd_ctl_elem_value_get_bytes()

const void * snd_ctl_elem_value_get_bytes | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the data stored within the element.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It returns the data stored in the element. Note that "bytes" elements don't have members. They have only one single block of data.

See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.

Returns
  Pointer to the elements data.

## ◆ snd_ctl_elem_value_get_device()

unsigned int snd_ctl_elem_value_get_device | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'device' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The device part of element identifier.

## ◆ snd_ctl_elem_value_get_enumerated()

unsigned int snd_ctl_elem_value_get_enumerated | ( | const snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx )

Get an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_ENUMERATED. It returns the index of the active item. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the requested member.

Returns
  The index of the active item.

## ◆ snd_ctl_elem_value_get_id()

void snd_ctl_elem_value_get_id | ( | const snd_ctl_elem_value_t * | obj,
|  | snd_ctl_elem_id_t * | ptr )

Get the element identifier from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  ptr | Pointer to an identifier object. The identifier is stored there.

## ◆ snd_ctl_elem_value_get_iec958()

void snd_ctl_elem_value_get_iec958 | ( | const snd_ctl_elem_value_t * | obj,
|  | snd_aes_iec958_t * | ptr )

Get an elements IEC958 data.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note that "IEC958" elements don't have members. They have only one single IEC958 information block.

See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  ptr | Pointer to an IEC958 structure. The data is stored there.

## ◆ snd_ctl_elem_value_get_index()

unsigned int snd_ctl_elem_value_get_index | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'index' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The index part of element identifier.

## ◆ snd_ctl_elem_value_get_integer()

long snd_ctl_elem_value_get_integer | ( | const snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx )

Get an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It returns the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.

Returns
  The members value.

## ◆ snd_ctl_elem_value_get_integer64()

long long snd_ctl_elem_value_get_integer64 | ( | const snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx )

Get an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It returns the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.

Returns
  The members value.

## ◆ snd_ctl_elem_value_get_interface()

snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'interface' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The interface part of element identifier.

## ◆ snd_ctl_elem_value_get_name()

const char * snd_ctl_elem_value_get_name | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'name' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The "name" part of element identifier.

## ◆ snd_ctl_elem_value_get_numid()

unsigned int snd_ctl_elem_value_get_numid | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'numid' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The numid.

## ◆ snd_ctl_elem_value_get_subdevice()

unsigned int snd_ctl_elem_value_get_subdevice | ( | const snd_ctl_elem_value_t * | obj | ) |

Get the identifiers 'subdevice' part from the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.

Returns
  The subdevice part of element identifier.

## ◆ snd_ctl_elem_value_malloc()

int snd_ctl_elem_value_malloc | ( | snd_ctl_elem_value_t ** | ptr | ) |

Allocate an invalid snd_ctl_elem_value_t on the heap.

Allocate space for a value object on the heap. The allocated memory must be freed using snd_ctl_elem_value_free().

See snd_ctl_elem_value_t for details.

Parameters

  ptr | Pointer to a snd_ctl_elem_value_t pointer. The address of the allocated space will be returned here.

Returns
  0 on success, otherwise a negative error code.

## ◆ snd_ctl_elem_value_set_boolean()

void snd_ctl_elem_value_set_boolean | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx,
|  | long | val )

Set an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It sets the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.
  val | The new value.

## ◆ snd_ctl_elem_value_set_byte()

void snd_ctl_elem_value_set_byte | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx,
|  | unsigned char | val )

Set an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It sets the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.
  val | The new value.

## ◆ snd_ctl_elem_value_set_device()

void snd_ctl_elem_value_set_device | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | val )

Set the identifiers 'device' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new device.

## ◆ snd_ctl_elem_value_set_enumerated()

void snd_ctl_elem_value_set_enumerated | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx,
|  | unsigned int | val )

Set an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_ENUMERATED. It activates the specified item. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the requested member.
  val | The new index of the item to be activated.

## ◆ snd_ctl_elem_value_set_id()

void snd_ctl_elem_value_set_id | ( | snd_ctl_elem_value_t * | obj,
|  | const snd_ctl_elem_id_t * | ptr )

Set the element identifier within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  ptr | The new identifier.

## ◆ snd_ctl_elem_value_set_iec958()

void snd_ctl_elem_value_set_iec958 | ( | snd_ctl_elem_value_t * | obj,
|  | const snd_aes_iec958_t * | ptr )

Set an elements IEC958 data.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note that "IEC958" elements don't have members. They have only one single IEC958 information block.

See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  ptr | Pointer to the new IEC958 data.

## ◆ snd_ctl_elem_value_set_index()

void snd_ctl_elem_value_set_index | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | val )

Set the identifiers 'index' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new index.

## ◆ snd_ctl_elem_value_set_integer()

void snd_ctl_elem_value_set_integer | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx,
|  | long | val )

Set an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It sets the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.
  val | The new value.

## ◆ snd_ctl_elem_value_set_integer64()

void snd_ctl_elem_value_set_integer64 | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | idx,
|  | long long | val )

Set an element members value.

Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It sets the value of one member. See snd_ctl_elem_value_t and Control interface for more details.

Parameters

  obj | The element value object.
  idx | The index of the member.
  val | The new value.

## ◆ snd_ctl_elem_value_set_interface()

void snd_ctl_elem_value_set_interface | ( | snd_ctl_elem_value_t * | obj,
|  | snd_ctl_elem_iface_t | val )

Set the identifiers 'interface' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new interface.

## ◆ snd_ctl_elem_value_set_name()

void snd_ctl_elem_value_set_name | ( | snd_ctl_elem_value_t * | obj,
|  | const char * | val )

Set the identifiers 'name' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new name.

## ◆ snd_ctl_elem_value_set_numid()

void snd_ctl_elem_value_set_numid | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | val )

Set the identifiers 'numid' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new numid.

## ◆ snd_ctl_elem_value_set_subdevice()

void snd_ctl_elem_value_set_subdevice | ( | snd_ctl_elem_value_t * | obj,
|  | unsigned int | val )

Set the identifiers 'subdevice' part within the given element value.

See snd_ctl_elem_value_t for more details.

Parameters

  obj | The element value.
  val | The new subdevice.

## ◆ snd_ctl_elem_value_sizeof()

size_t snd_ctl_elem_value_sizeof | ( | void |  | ) |

Get size of data structure for an element.

Returns
  Size in bytes.

## ◆ snd_ctl_elem_write()

int snd_ctl_elem_write | ( | snd_ctl_t * | ctl,
|  | snd_ctl_elem_value_t * | data )

Set CTL element value.

Write new value(s) to the sound card. You must set the ID and the value of the element before calling this function.

See snd_ctl_elem_value_t for details.

Parameters

  ctl | CTL handle.
  data | The new value.

Return values

  0 | on success
  >0 | on success when value was changed
  <0 | a negative error code

## ◆ snd_ctl_event_clear()

void snd_ctl_event_clear | ( | snd_ctl_event_t * | obj | ) |

clear given snd_ctl_event_t object

Parameters

  obj | pointer to object to clear

## ◆ snd_ctl_event_copy()

void snd_ctl_event_copy | ( | snd_ctl_event_t * | dst,
|  | const snd_ctl_event_t * | src )

copy one snd_ctl_event_t to another

Parameters

  dst | pointer to destination
  src | pointer to source

## ◆ snd_ctl_event_elem_get_device()

unsigned int snd_ctl_event_elem_get_device | ( | const snd_ctl_event_t * | obj | ) |

Get device part of CTL element identifier for an element related event.

Parameters

  obj | CTL event

Returns
  device part of element identifier

## ◆ snd_ctl_event_elem_get_id()

void snd_ctl_event_elem_get_id | ( | const snd_ctl_event_t * | obj,
|  | snd_ctl_elem_id_t * | ptr )

Get CTL element identifier for an element related event.

Parameters

  obj | CTL event
  ptr | Pointer to returned CTL element identifier

## ◆ snd_ctl_event_elem_get_index()

unsigned int snd_ctl_event_elem_get_index | ( | const snd_ctl_event_t * | obj | ) |

Get index part of CTL element identifier for an element related event.

Parameters

  obj | CTL event

Returns
  index part of element identifier

## ◆ snd_ctl_event_elem_get_interface()

snd_ctl_elem_iface_t snd_ctl_event_elem_get_interface | ( | const snd_ctl_event_t * | obj | ) |

Get interface part of CTL element identifier for an element related event.

Parameters

  obj | CTL event

Returns
  interface part of element identifier

## ◆ snd_ctl_event_elem_get_mask()

unsigned int snd_ctl_event_elem_get_mask | ( | const snd_ctl_event_t * | obj | ) |

Get event mask for an element related event.

Parameters

  obj | CTL event

Returns
  event mask for element related event

## ◆ snd_ctl_event_elem_get_name()

const char * snd_ctl_event_elem_get_name | ( | const snd_ctl_event_t * | obj | ) |

Get name part of CTL element identifier for an element related event.

Parameters

  obj | CTL event

Returns
  name part of element identifier

## ◆ snd_ctl_event_elem_get_numid()

unsigned int snd_ctl_event_elem_get_numid | ( | const snd_ctl_event_t * | obj | ) |

Get element numeric identifier for an element related event.

Parameters

  obj | CTL event

Returns
  element numeric identifier

## ◆ snd_ctl_event_elem_get_subdevice()

unsigned int snd_ctl_event_elem_get_subdevice | ( | const snd_ctl_event_t * | obj | ) |

Get subdevice part of CTL element identifier for an element related event.

Parameters

  obj | CTL event

Returns
  subdevice part of element identifier

## ◆ snd_ctl_event_free()

void snd_ctl_event_free | ( | snd_ctl_event_t * | obj | ) |

frees a previously allocated snd_ctl_event_t

Parameters

  obj | pointer to object to free

## ◆ snd_ctl_event_get_type()

snd_ctl_event_type_t snd_ctl_event_get_type | ( | const snd_ctl_event_t * | obj | ) |

Get type of a CTL event.

Parameters

  obj | CTL event

Returns
  CTL event type

## ◆ snd_ctl_event_malloc()

int snd_ctl_event_malloc | ( | snd_ctl_event_t ** | ptr | ) |

allocate an invalid snd_ctl_event_t using standard malloc

Parameters

  ptr | returned pointer

Returns
  0 on success otherwise negative error code

## ◆ snd_ctl_event_sizeof()

size_t snd_ctl_event_sizeof | ( | void |  | ) |

get size of snd_ctl_event_t

Returns
  size in bytes

## ◆ snd_ctl_event_type_name()

const char * snd_ctl_event_type_name | ( | snd_ctl_event_type_t | type | ) |

get name of a CTL event type

Parameters

  type | CTL event type

Returns
  ascii name of CTL event type

## ◆ snd_ctl_get_dB_range()

int snd_ctl_get_dB_range | ( | snd_ctl_t * | ctl,
|  | const snd_ctl_elem_id_t * | id,
|  | long * | min,
|  | long * | max )

Get the dB min/max values on the given control element.

Parameters

  ctl | the control handler
  id | the element id
  min | the pointer to store the minimum dB value (in 0.01dB unit)
  max | the pointer to store the maximum dB value (in 0.01dB unit)

Returns
  0 if successful, or a negative error code

## ◆ snd_ctl_get_power_state()

int snd_ctl_get_power_state | ( | snd_ctl_t * | ctl,
|  | unsigned int * | state )

Get actual Power State.

Parameters

  ctl | CTL handle
  state | Destination value

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_name()

const char * snd_ctl_name | ( | snd_ctl_t * | ctl | ) |

get identifier of CTL handle

Parameters

  ctl | CTL handle

Returns
  ascii identifier of CTL handle

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

## ◆ snd_ctl_nonblock()

int snd_ctl_nonblock | ( | snd_ctl_t * | ctl,
|  | int | nonblock )

set nonblock mode

Parameters

  ctl | CTL handle
  nonblock | 0 = block, 1 = nonblock mode, 2 = abort

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_open()

int snd_ctl_open | ( | snd_ctl_t ** | ctlp,
|  | const char * | name,
|  | int | mode )

Opens a sound card.

Parameters

  ctlp | Returned CTL handle.
  name | A string identifying the card (See Identifying and Opening Control Interfaces).
  mode | Open mode (see SND_CTL_NONBLOCK, SND_CTL_ASYNC).

Returns
  0 on success otherwise a negative error code.

## ◆ snd_ctl_open_fallback()

int snd_ctl_open_fallback | ( | snd_ctl_t ** | ctlp,
|  | snd_config_t * | root,
|  | const char * | name,
|  | const char * | orig_name,
|  | int | mode )

Opens a fallback CTL.

Parameters

  ctlp | Returned CTL handle
  root | Configuration root
  name | ASCII identifier of the CTL handle used as fallback
  orig_name | The original ASCII name
  mode | Open mode (see SND_CTL_NONBLOCK, SND_CTL_ASYNC)

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_open_lconf()

int snd_ctl_open_lconf | ( | snd_ctl_t ** | ctlp,
|  | const char * | name,
|  | int | mode,
|  | snd_config_t * | lconf )

Opens a CTL using local configuration.

Parameters

  ctlp | Returned CTL handle
  name | ASCII identifier of the CTL handle
  mode | Open mode (see SND_CTL_NONBLOCK, SND_CTL_ASYNC)
  lconf | Local configuration

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_poll_descriptors()

int snd_ctl_poll_descriptors | ( | snd_ctl_t * | ctl,
|  | struct pollfd * | pfds,
|  | unsigned int | space )

get poll descriptors

Parameters

  ctl | CTL handle
  pfds | array of poll descriptors
  space | space in the poll descriptor array

Returns
  count of filled descriptors

## ◆ snd_ctl_poll_descriptors_count()

int snd_ctl_poll_descriptors_count | ( | snd_ctl_t * | ctl | ) |

get count of poll descriptors for CTL handle

Parameters

  ctl | CTL handle

Returns
  count of poll descriptors

## ◆ snd_ctl_poll_descriptors_revents()

int snd_ctl_poll_descriptors_revents | ( | snd_ctl_t * | ctl,
|  | struct pollfd * | pfds,
|  | unsigned int | nfds,
|  | unsigned short * | revents )

get returned events from poll descriptors

Parameters

  ctl | CTL handle
  pfds | array of poll descriptors
  nfds | count of poll descriptors
  revents | returned events

Returns
  zero if success, otherwise a negative error code

## ◆ snd_ctl_read()

int snd_ctl_read | ( | snd_ctl_t * | ctl,
|  | snd_ctl_event_t * | event )

Read an event.

Parameters

  ctl | CTL handle
  event | Event pointer

Returns
  number of events read otherwise a negative error code on failure

## ◆ snd_ctl_set_power_state()

int snd_ctl_set_power_state | ( | snd_ctl_t * | ctl,
|  | unsigned int | state )

Set Power State to given SND_CTL_POWER_* value and do the power management.

Parameters

  ctl | CTL handle
  state | Desired Power State

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_subscribe_events()

int snd_ctl_subscribe_events | ( | snd_ctl_t * | ctl,
|  | int | subscribe )

Ask to be informed about events (poll, snd_async_add_ctl_handler, snd_ctl_read)

Parameters

  ctl | CTL handle
  subscribe | 0 = unsubscribe, 1 = subscribe, -1 = check subscribe or not

Returns
  0 on success otherwise a negative error code

## ◆ snd_ctl_type()

snd_ctl_type_t snd_ctl_type | ( | snd_ctl_t * | ctl | ) |

get type of CTL handle

Parameters

  ctl | CTL handle

Returns
  type of CTL handle

Returns the type snd_ctl_type_t of given CTL handle.

## ◆ snd_ctl_wait()

int snd_ctl_wait | ( | snd_ctl_t * | ctl,
|  | int | timeout )

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

Parameters

  ctl | CTL handle
  timeout | maximum time in milliseconds to wait

Returns
  0 otherwise a negative error code on failure

## ◆ snd_tlv_convert_from_dB()

int snd_tlv_convert_from_dB | ( | unsigned int * | tlv,
|  | long | rangemin,
|  | long | rangemax,
|  | long | db_gain,
|  | long * | value,
|  | int | xdir )

Convert from dB gain to the corresponding raw value.

Parameters

  tlv | the TLV source returned by snd_tlv_parse_dB_info()
  rangemin | the minimum value of the raw volume
  rangemax | the maximum value of the raw volume
  db_gain | the dB gain to convert (in 0.01dB unit)
  value | the pointer to store the converted raw volume value
  xdir | the direction for round-up. The value is round up when this is positive. A negative value means round down. Zero means round-up to nearest.

Returns
  0 if successful, or a negative error code

## ◆ snd_tlv_convert_to_dB()

int snd_tlv_convert_to_dB | ( | unsigned int * | tlv,
|  | long | rangemin,
|  | long | rangemax,
|  | long | volume,
|  | long * | db_gain )

Convert the given raw volume value to a dB gain.

Parameters

  tlv | the TLV source returned by snd_tlv_parse_dB_info()
  rangemin | the minimum value of the raw volume
  rangemax | the maximum value of the raw volume
  volume | the raw volume value to convert
  db_gain | the dB gain (in 0.01dB unit)

Returns
  0 if successful, or a negative error code

## ◆ snd_tlv_get_dB_range()

int snd_tlv_get_dB_range | ( | unsigned int * | tlv,
|  | long | rangemin,
|  | long | rangemax,
|  | long * | min,
|  | long * | max )

Get the dB min/max values.

Parameters

  tlv | the TLV source returned by snd_tlv_parse_dB_info()
  rangemin | the minimum value of the raw volume
  rangemax | the maximum value of the raw volume
  min | the pointer to store the minimum dB value (in 0.01dB unit)
  max | the pointer to store the maximum dB value (in 0.01dB unit)

Returns
  0 if successful, or a negative error code

## ◆ snd_tlv_parse_dB_info()

int snd_tlv_parse_dB_info | ( | unsigned int * | tlv,
|  | unsigned int | tlv_size,
|  | unsigned int ** | db_tlvp )

Parse TLV stream and retrieve dB information.

Parameters

  tlv | the TLV source
  tlv_size | the byte size of TLV source
  db_tlvp | the pointer stored the dB TLV information

Returns
  the byte size of dB TLV information if found in the given TLV source, or a negative error code.

This function parses the given TLV source and stores the TLV start point if the TLV information regarding dB conversion is found. The stored TLV pointer can be passed to the convesion functions snd_tlv_convert_to_dB(), snd_tlv_convert_from_dB() and snd_tlv_get_dB_range().