High level Control Interface
[Control Interface]

Typedefs
typedef _snd_hctl_elem	snd_hctl_elem_t
typedef _snd_hctl	snd_hctl_t
typedef int(*)	snd_hctl_compare_t (const snd_hctl_elem_t *e1, const snd_hctl_elem_t *e2)
	Compare function for sorting HCTL elements.
typedef int(*)	snd_hctl_callback_t (snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem)
	HCTL callback function.
typedef int(*)	snd_hctl_elem_callback_t (snd_hctl_elem_t *elem, unsigned int mask)
	HCTL element callback function.
Functions
int	snd_hctl_compare_fast (const snd_hctl_elem_t *c1, const snd_hctl_elem_t *c2)
	A "don't care" fast compare functions that may be used with snd_hctl_set_compare.
int	snd_hctl_open (snd_hctl_t **hctl, const char *name, int mode)
	Opens an HCTL.
int	snd_hctl_open_ctl (snd_hctl_t **hctlp, snd_ctl_t *ctl)
	Opens an HCTL.
int	snd_hctl_close (snd_hctl_t *hctl)
	close HCTL handle
int	snd_hctl_nonblock (snd_hctl_t *hctl, int nonblock)
	set nonblock mode
int	snd_hctl_poll_descriptors_count (snd_hctl_t *hctl)
	get count of poll descriptors for HCTL handle
int	snd_hctl_poll_descriptors (snd_hctl_t *hctl, struct pollfd *pfds, unsigned int space)
	get poll descriptors
int	snd_hctl_poll_descriptors_revents (snd_hctl_t *ctl, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
	get returned events from poll descriptors
unsigned int	snd_hctl_get_count (snd_hctl_t *hctl)
	Get number of loaded elements for an HCTL.
int	snd_hctl_set_compare (snd_hctl_t *hctl, snd_hctl_compare_t hsort)
	Change HCTL compare function and reorder elements.
snd_hctl_elem_t *	snd_hctl_first_elem (snd_hctl_t *hctl)
	get first element for an HCTL
snd_hctl_elem_t *	snd_hctl_last_elem (snd_hctl_t *hctl)
	get last element for an HCTL
snd_hctl_elem_t *	snd_hctl_find_elem (snd_hctl_t *hctl, const snd_ctl_elem_id_t *id)
	Search an HCTL element.
void	snd_hctl_set_callback (snd_hctl_t *hctl, snd_hctl_callback_t callback)
	Set callback function for an HCTL.
void	snd_hctl_set_callback_private (snd_hctl_t *hctl, void *data)
	Set callback private value for an HCTL.
void *	snd_hctl_get_callback_private (snd_hctl_t *hctl)
	Get callback private value for an HCTL.
int	snd_hctl_load (snd_hctl_t *hctl)
	Load an HCTL with all elements and sort them.
int	snd_hctl_free (snd_hctl_t *hctl)
	free HCTL loaded elements
int	snd_hctl_handle_events (snd_hctl_t *hctl)
	Handle pending HCTL events invoking callbacks.
const char *	snd_hctl_name (snd_hctl_t *hctl)
	get identifier of HCTL handle
int	snd_hctl_wait (snd_hctl_t *hctl, int timeout)
	Wait for a HCTL to become ready (i.e. at least one event pending).
snd_ctl_t *	snd_hctl_ctl (snd_hctl_t *hctl)
	Get a ctl handle associated to the given hctl handle.
snd_hctl_elem_t *	snd_hctl_elem_next (snd_hctl_elem_t *elem)
	get next HCTL element
snd_hctl_elem_t *	snd_hctl_elem_prev (snd_hctl_elem_t *elem)
	get previous HCTL element
int	snd_hctl_elem_info (snd_hctl_elem_t *elem, snd_ctl_elem_info_t *info)
	Get information for an HCTL element.
int	snd_hctl_elem_read (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
	Get value for an HCTL element.
int	snd_hctl_elem_write (snd_hctl_elem_t *elem, snd_ctl_elem_value_t *value)
	Set value for an HCTL element.
int	snd_hctl_elem_tlv_read (snd_hctl_elem_t *elem, unsigned int *tlv, unsigned int tlv_size)
	Get TLV value for an HCTL element.
int	snd_hctl_elem_tlv_write (snd_hctl_elem_t *elem, const unsigned int *tlv)
	Set TLV value for an HCTL element.
int	snd_hctl_elem_tlv_command (snd_hctl_elem_t *elem, const unsigned int *tlv)
	Set TLV value for an HCTL element.
snd_hctl_t *	snd_hctl_elem_get_hctl (snd_hctl_elem_t *elem)
	Get HCTL handle for an HCTL element.
void	snd_hctl_elem_get_id (const snd_hctl_elem_t *obj, snd_ctl_elem_id_t *ptr)
	Get CTL element identifier of a CTL element id/value.
unsigned int	snd_hctl_elem_get_numid (const snd_hctl_elem_t *obj)
	Get element numeric identifier of a CTL element id/value.
snd_ctl_elem_iface_t	snd_hctl_elem_get_interface (const snd_hctl_elem_t *obj)
	Get interface part of CTL element identifier of a CTL element id/value.
unsigned int	snd_hctl_elem_get_device (const snd_hctl_elem_t *obj)
	Get device part of CTL element identifier of a CTL element id/value.
unsigned int	snd_hctl_elem_get_subdevice (const snd_hctl_elem_t *obj)
	Get subdevice part of CTL element identifier of a CTL element id/value.
const char *	snd_hctl_elem_get_name (const snd_hctl_elem_t *obj)
	Get name part of CTL element identifier of a CTL element id/value.
unsigned int	snd_hctl_elem_get_index (const snd_hctl_elem_t *obj)
	Get index part of CTL element identifier of a CTL element id/value.
void	snd_hctl_elem_set_callback (snd_hctl_elem_t *obj, snd_hctl_elem_callback_t val)
	Set callback function for an HCTL element.
void *	snd_hctl_elem_get_callback_private (const snd_hctl_elem_t *obj)
	Get callback private value for an HCTL element.
void	snd_hctl_elem_set_callback_private (snd_hctl_elem_t *obj, void *val)
	Set callback private value for an HCTL element.

---

Detailed Description

The high level control interface. See High level control interface page for more details.

---

Typedef Documentation

typedef int(*) snd_hctl_callback_t(snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem)

HCTL callback function.

Parameters:

	hctl	HCTL handle
	mask	event mask
	elem	related HCTL element (if any)

Returns:

0 on success otherwise a negative error code

typedef int(*) snd_hctl_compare_t(const snd_hctl_elem_t *e1, const snd_hctl_elem_t *e2)

Compare function for sorting HCTL elements.

Parameters:

	e1	First element
	e2	Second element

Returns:

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

typedef int(*) snd_hctl_elem_callback_t(snd_hctl_elem_t *elem, unsigned int mask)

HCTL element callback function.

Parameters:

	elem	HCTL element
	mask	event mask

Returns:

0 on success otherwise a negative error code

typedef struct _snd_hctl_elem snd_hctl_elem_t

HCTL element handle

typedef struct _snd_hctl snd_hctl_t

HCTL handle

---

Function Documentation

int snd_hctl_close

(

snd_hctl_t *

hctl

)

close HCTL handle

Parameters:

hctl

HCTL handle

Returns:

0 on success otherwise a negative error code

Closes the specified HCTL handle and frees all associated resources.

int snd_hctl_compare_fast	(	const snd_hctl_elem_t *	c1,
		const snd_hctl_elem_t *	c2
	)

A "don't care" fast compare functions that may be used with snd_hctl_set_compare.

Parameters:

	c1	First HCTL element
	c2	Second HCTL element

Returns:

-1 if c1 < c2, 0 if c1 == c2, 1 if c1 > c2

snd_ctl_t* snd_hctl_ctl

(

snd_hctl_t *

hctl

)

Get a ctl handle associated to the given hctl handle.

Parameters:

hctl

HCTL handle

Returns:

a ctl handle otherwise NULL

void* snd_hctl_elem_get_callback_private

(

const snd_hctl_elem_t *

obj

)

Get callback private value for an HCTL element.

Parameters:

obj

HCTL element

Returns:

callback private value

unsigned int snd_hctl_elem_get_device

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

device part of element identifier

snd_hctl_t* snd_hctl_elem_get_hctl

(

snd_hctl_elem_t *

elem

)

Get HCTL handle for an HCTL element.

Parameters:

elem

HCTL element

Returns:

HCTL handle

void snd_hctl_elem_get_id	(	const snd_hctl_elem_t *	obj,
		snd_ctl_elem_id_t *	ptr
	)

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

Parameters:

	obj	CTL element id/value
	ptr	Pointer to returned CTL element identifier

unsigned int snd_hctl_elem_get_index

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

index part of element identifier

snd_ctl_elem_iface_t snd_hctl_elem_get_interface

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

interface part of element identifier

const char* snd_hctl_elem_get_name

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

name part of element identifier

unsigned int snd_hctl_elem_get_numid

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

element numeric identifier

unsigned int snd_hctl_elem_get_subdevice

(

const snd_hctl_elem_t *

obj

)

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

Parameters:

obj

CTL element id/value

Returns:

subdevice part of element identifier

int snd_hctl_elem_info	(	snd_hctl_elem_t *	elem,
		snd_ctl_elem_info_t *	info
	)

Get information for an HCTL element.

Parameters:

	elem	HCTL element
	info	HCTL element information

Returns:

0 otherwise a negative error code on failure

snd_hctl_elem_t* snd_hctl_elem_next

(

snd_hctl_elem_t *

elem

)

get next HCTL element

Parameters:

elem

HCTL element

Returns:

pointer to next element

snd_hctl_elem_t* snd_hctl_elem_prev

(

snd_hctl_elem_t *

elem

)

get previous HCTL element

Parameters:

elem

HCTL element

Returns:

pointer to previous element

int snd_hctl_elem_read	(	snd_hctl_elem_t *	elem,
		snd_ctl_elem_value_t *	value
	)

Get value for an HCTL element.

Parameters:

	elem	HCTL element
	value	HCTL element value

Returns:

0 otherwise a negative error code on failure

void snd_hctl_elem_set_callback	(	snd_hctl_elem_t *	obj,
		snd_hctl_elem_callback_t	val
	)

Set callback function for an HCTL element.

Parameters:

	obj	HCTL element
	val	callback function

void snd_hctl_elem_set_callback_private	(	snd_hctl_elem_t *	obj,
		void *	val
	)

Set callback private value for an HCTL element.

Parameters:

	obj	HCTL element
	val	callback private value

int snd_hctl_elem_tlv_command	(	snd_hctl_elem_t *	elem,
		const unsigned int *	tlv
	)

Set TLV value for an HCTL element.

Parameters:

	elem	HCTL element
	tlv	TLV array for value

Return values:

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

int snd_hctl_elem_tlv_read	(	snd_hctl_elem_t *	elem,
		unsigned int *	tlv,
		unsigned int	tlv_size
	)

Get TLV value for an HCTL element.

Parameters:

	elem	HCTL element
	tlv	TLV array for value
	tlv_size	size of TLV array in bytes

Returns:

0 otherwise a negative error code on failure

int snd_hctl_elem_tlv_write	(	snd_hctl_elem_t *	elem,
		const unsigned int *	tlv
	)

Set TLV value for an HCTL element.

Parameters:

	elem	HCTL element
	tlv	TLV array for value

Return values:

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

int snd_hctl_elem_write	(	snd_hctl_elem_t *	elem,
		snd_ctl_elem_value_t *	value
	)

Set value for an HCTL element.

Parameters:

	elem	HCTL element
	value	HCTL element value

Return values:

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

snd_hctl_elem_t* snd_hctl_find_elem	(	snd_hctl_t *	hctl,
		const snd_ctl_elem_id_t *	id
	)

Search an HCTL element.

Parameters:

	hctl	HCTL handle
	id	Element identifier

Returns:

pointer to found HCTL element or NULL if it does not exists

snd_hctl_elem_t* snd_hctl_first_elem

(

snd_hctl_t *

hctl

)

get first element for an HCTL

Parameters:

hctl

HCTL handle

Returns:

pointer to first element

int snd_hctl_free

(

snd_hctl_t *

hctl

)

free HCTL loaded elements

Parameters:

hctl

HCTL handle

Returns:

0 on success otherwise a negative error code

void* snd_hctl_get_callback_private

(

snd_hctl_t *

hctl

)

Get callback private value for an HCTL.

Parameters:

hctl

HCTL handle

Returns:

callback private value

unsigned int snd_hctl_get_count

(

snd_hctl_t *

hctl

)

Get number of loaded elements for an HCTL.

Parameters:

hctl

HCTL handle

Returns:

elements count

int snd_hctl_handle_events

(

snd_hctl_t *

hctl

)

Handle pending HCTL events invoking callbacks.

Parameters:

hctl

HCTL handle

Returns:

0 otherwise a negative error code on failure

snd_hctl_elem_t* snd_hctl_last_elem

(

snd_hctl_t *

hctl

)

get last element for an HCTL

Parameters:

hctl

HCTL handle

Returns:

pointer to last element

int snd_hctl_load

(

snd_hctl_t *

hctl

)

Load an HCTL with all elements and sort them.

Parameters:

hctl

HCTL handle

Returns:

0 on success otherwise a negative error code

const char* snd_hctl_name

(

snd_hctl_t *

hctl

)

get identifier of HCTL handle

Parameters:

hctl

HCTL handle

Returns:

ascii identifier of HCTL handle

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

int snd_hctl_nonblock	(	snd_hctl_t *	hctl,
		int	nonblock
	)

set nonblock mode

Parameters:

	hctl	HCTL handle
	nonblock	0 = block, 1 = nonblock mode

Returns:

0 on success otherwise a negative error code

int snd_hctl_open	(	snd_hctl_t **	hctlp,
		const char *	name,
		int	mode
	)

Opens an HCTL.

Parameters:

	hctlp	Returned HCTL handle
	name	ASCII identifier of the underlying CTL handle
	mode	Open mode (see SND_CTL_NONBLOCK, SND_CTL_ASYNC)

Returns:

0 on success otherwise a negative error code

int snd_hctl_open_ctl	(	snd_hctl_t **	hctlp,
		snd_ctl_t *	ctl
	)

Opens an HCTL.

Parameters:

	hctlp	Returned HCTL handle
	ctl	underlying CTL handle

Returns:

0 on success otherwise a negative error code

int snd_hctl_poll_descriptors	(	snd_hctl_t *	hctl,
		struct pollfd *	pfds,
		unsigned int	space
	)

get poll descriptors

Parameters:

	hctl	HCTL handle
	pfds	array of poll descriptors
	space	space in the poll descriptor array

Returns:

count of filled descriptors

int snd_hctl_poll_descriptors_count

(

snd_hctl_t *

hctl

)

get count of poll descriptors for HCTL handle

Parameters:

hctl

HCTL handle

Returns:

count of poll descriptors

int snd_hctl_poll_descriptors_revents	(	snd_hctl_t *	hctl,
		struct pollfd *	pfds,
		unsigned int	nfds,
		unsigned short *	revents
	)

get returned events from poll descriptors

Parameters:

	hctl	HCTL handle
	pfds	array of poll descriptors
	nfds	count of poll descriptors
	revents	returned events

Returns:

zero if success, otherwise a negative error code

void snd_hctl_set_callback	(	snd_hctl_t *	hctl,
		snd_hctl_callback_t	callback
	)

Set callback function for an HCTL.

Parameters:

	hctl	HCTL handle
	callback	callback function

void snd_hctl_set_callback_private	(	snd_hctl_t *	hctl,
		void *	callback_private
	)

Set callback private value for an HCTL.

Parameters:

	hctl	HCTL handle
	callback_private	callback private value

int snd_hctl_set_compare	(	snd_hctl_t *	hctl,
		snd_hctl_compare_t	compare
	)

Change HCTL compare function and reorder elements.

Parameters:

	hctl	HCTL handle
	compare	Element compare function

Returns:

0 on success otherwise a negative error code

int snd_hctl_wait	(	snd_hctl_t *	hctl,
		int	timeout
	)

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

Parameters:

	hctl	HCTL handle
	timeout	maximum time in milliseconds to wait

Returns:

a positive value on success otherwise a negative error code

Return values:

	0	timeout occurred
	1	an event is pending

---