High level Control Interface

Overview

The high level control interface. More…

// typedefs

typedef struct _snd_hctl_elem snd_hctl_elem_t;
typedef struct _snd_hctl snd_hctl_t;

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

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

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

// global functions

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

int
snd_hctl_open(
    snd_hctl_t** hctl,
    const char* name,
    int mode
);

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

int
snd_hctl_close(snd_hctl_t* hctl);

int
snd_hctl_nonblock(
    snd_hctl_t* hctl,
    int nonblock
);

static
__inline__ int
snd_hctl_abort(snd_hctl_t* hctl);

int
snd_hctl_poll_descriptors_count(snd_hctl_t* hctl);

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

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

unsigned int
snd_hctl_get_count(snd_hctl_t* hctl);

int
snd_hctl_set_compare(
    snd_hctl_t* hctl,
    snd_hctl_compare_t hsort
);

snd_hctl_elem_t*
snd_hctl_first_elem(snd_hctl_t* hctl);

snd_hctl_elem_t*
snd_hctl_last_elem(snd_hctl_t* hctl);

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

void
snd_hctl_set_callback(
    snd_hctl_t* hctl,
    snd_hctl_callback_t callback
);

void
snd_hctl_set_callback_private(
    snd_hctl_t* hctl,
    void* data
);

void*
snd_hctl_get_callback_private(snd_hctl_t* hctl);

int
snd_hctl_load(snd_hctl_t* hctl);

int
snd_hctl_free(snd_hctl_t* hctl);

int
snd_hctl_handle_events(snd_hctl_t* hctl);

const char*
snd_hctl_name(snd_hctl_t* hctl);

int
snd_hctl_wait(
    snd_hctl_t* hctl,
    int timeout
);

snd_ctl_t*
snd_hctl_ctl(snd_hctl_t* hctl);

snd_hctl_elem_t*
snd_hctl_elem_next(snd_hctl_elem_t* elem);

snd_hctl_elem_t*
snd_hctl_elem_prev(snd_hctl_elem_t* elem);

int
snd_hctl_elem_info(
    snd_hctl_elem_t* elem,
    snd_ctl_elem_info_t* info
);

int
snd_hctl_elem_read(
    snd_hctl_elem_t* elem,
    snd_ctl_elem_value_t* value
);

int
snd_hctl_elem_write(
    snd_hctl_elem_t* elem,
    snd_ctl_elem_value_t* value
);

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

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

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

snd_hctl_t*
snd_hctl_elem_get_hctl(snd_hctl_elem_t* elem);

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

unsigned int
snd_hctl_elem_get_numid(const snd_hctl_elem_t* obj);

snd_ctl_elem_iface_t
snd_hctl_elem_get_interface(const snd_hctl_elem_t* obj);

unsigned int
snd_hctl_elem_get_device(const snd_hctl_elem_t* obj);

unsigned int
snd_hctl_elem_get_subdevice(const snd_hctl_elem_t* obj);

const char*
snd_hctl_elem_get_name(const snd_hctl_elem_t* obj);

unsigned int
snd_hctl_elem_get_index(const snd_hctl_elem_t* obj);

void
snd_hctl_elem_set_callback(
    snd_hctl_elem_t* obj,
    snd_hctl_elem_callback_t val
);

void*
snd_hctl_elem_get_callback_private(const snd_hctl_elem_t* obj);

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

Detailed Documentation

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

Typedefs

typedef struct _snd_hctl_elem snd_hctl_elem_t

HCTL element handle

typedef struct _snd_hctl snd_hctl_t

HCTL handle

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

Global 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.

Parameters:

c1	First HCTL element
c2	Second HCTL element

Returns:

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

int
snd_hctl_open(
    snd_hctl_t** hctl,
    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_close(snd_hctl_t* hctl)

close HCTL handle

Closes the specified HCTL handle and frees all associated resources.

Parameters:

hctl	HCTL handle

Returns:

0 on success otherwise a negative error code

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_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(
    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_revents(
    snd_hctl_t* ctl,
    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

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_set_compare(
    snd_hctl_t* hctl,
    snd_hctl_compare_t hsort
)

Change HCTL compare function and reorder elements.

Parameters:

hctl	HCTL handle
compare	Element compare function

Returns:

0 on success otherwise a negative error code

snd_hctl_elem_t*
snd_hctl_first_elem(snd_hctl_t* hctl)

get first element for an HCTL

Parameters:

hctl	HCTL handle

Returns:

pointer to first element

snd_hctl_elem_t*
snd_hctl_last_elem(snd_hctl_t* hctl)

get last element for an HCTL

Parameters:

hctl	HCTL handle

Returns:

pointer to last element

snd_hctl_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

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* data
)

Set callback private value for an HCTL.

Parameters:

hctl	HCTL handle
callback_private	callback private value

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

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

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

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

const char*
snd_hctl_name(snd_hctl_t* hctl)

get identifier of HCTL handle

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

Parameters:

hctl	HCTL handle

Returns:

ascii 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)

Parameters:

hctl	HCTL handle
timeout	maximum time in milliseconds to wait
0	timeout occurred
1	an event is pending

Returns:

a positive value on success otherwise a negative error code

snd_ctl_t*
snd_hctl_ctl(snd_hctl_t* hctl)

Get a ctl handle associated to the given hctl handle.

Parameters:

hctl	HCTL handle

Returns:

a ctl handle otherwise NULL

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

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

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
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
0	on success
>1	on success when value was changed
<0	a negative error code on failure

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
0	on success
>1	on success when value was changed
<0	a negative error code on failure

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_numid(const snd_hctl_elem_t* obj)

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

Parameters:

obj	CTL element id/value

Returns:

element numeric identifier

snd_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

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

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

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

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

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