Mixer Interface

Overview

The mixer interface. More…

Simple Mixer Interface

// typedefs

typedef struct _snd_mixer snd_mixer_t;
typedef struct _snd_mixer_class snd_mixer_class_t;
typedef struct _snd_mixer_elem snd_mixer_elem_t;

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

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

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

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

// enums

enum snd_mixer_elem_type_t;

// global functions

int
snd_mixer_open(
    snd_mixer_t** mixer,
    int mode
);

int
snd_mixer_close(snd_mixer_t* mixer);

snd_mixer_elem_t*
snd_mixer_first_elem(snd_mixer_t* mixer);

snd_mixer_elem_t*
snd_mixer_last_elem(snd_mixer_t* mixer);

int
snd_mixer_handle_events(snd_mixer_t* mixer);

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

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

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

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

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

int
snd_mixer_poll_descriptors_count(snd_mixer_t* mixer);

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

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

int
snd_mixer_load(snd_mixer_t* mixer);

void
snd_mixer_free(snd_mixer_t* mixer);

int
snd_mixer_wait(
    snd_mixer_t* mixer,
    int timeout
);

int
snd_mixer_set_compare(
    snd_mixer_t* mixer,
    snd_mixer_compare_t msort
);

void
snd_mixer_set_callback(
    snd_mixer_t* obj,
    snd_mixer_callback_t val
);

void*
snd_mixer_get_callback_private(const snd_mixer_t* obj);

void
snd_mixer_set_callback_private(
    snd_mixer_t* obj,
    void* val
);

unsigned int
snd_mixer_get_count(const snd_mixer_t* obj);

int
snd_mixer_class_unregister(snd_mixer_class_t* clss);

snd_mixer_elem_t*
snd_mixer_elem_next(snd_mixer_elem_t* elem);

snd_mixer_elem_t*
snd_mixer_elem_prev(snd_mixer_elem_t* elem);

void
snd_mixer_elem_set_callback(
    snd_mixer_elem_t* obj,
    snd_mixer_elem_callback_t val
);

void*
snd_mixer_elem_get_callback_private(const snd_mixer_elem_t* obj);

void
snd_mixer_elem_set_callback_private(
    snd_mixer_elem_t* obj,
    void* val
);

snd_mixer_elem_type_t
snd_mixer_elem_get_type(const snd_mixer_elem_t* obj);

int
snd_mixer_class_register(
    snd_mixer_class_t* class_,
    snd_mixer_t* mixer
);

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

int
snd_mixer_elem_add(
    snd_mixer_elem_t* elem,
    snd_mixer_class_t* class_
);

int
snd_mixer_elem_remove(snd_mixer_elem_t* elem);

void
snd_mixer_elem_free(snd_mixer_elem_t* elem);

int
snd_mixer_elem_info(snd_mixer_elem_t* elem);

int
snd_mixer_elem_value(snd_mixer_elem_t* elem);

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

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

int
snd_mixer_elem_empty(snd_mixer_elem_t* melem);

void*
snd_mixer_elem_get_private(const snd_mixer_elem_t* melem);

size_t
snd_mixer_class_sizeof(void);

int
snd_mixer_class_malloc(snd_mixer_class_t** ptr);

void
snd_mixer_class_free(snd_mixer_class_t* obj);

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

snd_mixer_t*
snd_mixer_class_get_mixer(const snd_mixer_class_t* class_);

snd_mixer_event_t
snd_mixer_class_get_event(const snd_mixer_class_t* class_);

void*
snd_mixer_class_get_private(const snd_mixer_class_t* class_);

snd_mixer_compare_t
snd_mixer_class_get_compare(const snd_mixer_class_t* class_);

int
snd_mixer_class_set_event(
    snd_mixer_class_t* class_,
    snd_mixer_event_t event
);

int
snd_mixer_class_set_private(
    snd_mixer_class_t* class_,
    void* private_data
);

int
snd_mixer_class_set_private_free(
    snd_mixer_class_t* class_,
    void(*)(snd_mixer_class_t*) private_free
);

int
snd_mixer_class_set_compare(
    snd_mixer_class_t* class_,
    snd_mixer_compare_t compare
);

// macros

#define snd_mixer_class_alloca(ptr)

Detailed Documentation

The mixer interface.

Typedefs

typedef struct _snd_mixer snd_mixer_t

Mixer handle

typedef struct _snd_mixer_class snd_mixer_class_t

Mixer elements class handle

typedef struct _snd_mixer_elem snd_mixer_elem_t

Mixer element handle

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

Mixer callback function.

Parameters:

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

Returns:

0 on success otherwise a negative error code

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

Mixer element callback function.

Parameters:

elem	Mixer element
mask	event mask

Returns:

0 on success otherwise a negative error code

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

Compare function for sorting mixer elements.

Parameters:

e1	First element
e2	Second element

Returns:

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

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

Event callback for the mixer class.

Parameters:

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

Returns:

zero if success, otherwise a negative error value

Global Functions

int
snd_mixer_open(
    snd_mixer_t** mixer,
    int mode
)

Opens an empty mixer.

Parameters:

mixerp	Returned mixer handle
mode	Open mode

Returns:

0 on success otherwise a negative error code

int
snd_mixer_close(snd_mixer_t* mixer)

Close a mixer and free all related resources.

Parameters:

mixer

Mixer handle

Returns:

0 on success otherwise a negative error code

snd_mixer_elem_t*
snd_mixer_first_elem(snd_mixer_t* mixer)

get first element for a mixer

Parameters:

mixer

Mixer handle

Returns:

pointer to first element

snd_mixer_elem_t*
snd_mixer_last_elem(snd_mixer_t* mixer)

get last element for a mixer

Parameters:

mixer

Mixer handle

Returns:

pointer to last element

int
snd_mixer_handle_events(snd_mixer_t* mixer)

Handle pending mixer events invoking callbacks.

Parameters:

mixer

Mixer handle

Returns:

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

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

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

Parameters:

mixer	Mixer handle
name	HCTL name (see snd_hctl_open)

Returns:

0 on success otherwise a negative error code

int
snd_mixer_attach_hctl(
    snd_mixer_t* mixer,
    snd_hctl_t* hctl
)

Attach an HCTL to an opened mixer.

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

Parameters:

mixer	Mixer handle
hctl	the HCTL to be attached

Returns:

0 on success otherwise a negative error code

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

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

Parameters:

mixer	Mixer handle
name	HCTL previously attached

Returns:

0 on success otherwise a negative error code

int
snd_mixer_detach_hctl(
    snd_mixer_t* mixer,
    snd_hctl_t* hctl
)

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

Note: The hctl handle is not closed!

Parameters:

mixer	Mixer handle
hctl	HCTL previously attached

Returns:

0 on success otherwise a negative error code

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

Obtain a HCTL pointer associated to given name.

Parameters:

mixer	Mixer handle
name	HCTL previously attached
hctl	HCTL pointer

Returns:

0 on success otherwise a negative error code

int
snd_mixer_poll_descriptors_count(snd_mixer_t* mixer)

get count of poll descriptors for mixer handle

Parameters:

mixer

Mixer handle

Returns:

count of poll descriptors

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

get poll descriptors

Parameters:

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

Returns:

count of filled descriptors

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

get returned events from poll descriptors

Parameters:

mixer	Mixer handle
pfds	array of poll descriptors
nfds	count of poll descriptors
revents	returned events

Returns:

zero if success, otherwise a negative error code

int
snd_mixer_load(snd_mixer_t* mixer)

Load a mixer elements.

Parameters:

mixer

Mixer handle

Returns:

0 on success otherwise a negative error code

void
snd_mixer_free(snd_mixer_t* mixer)

Unload all mixer elements and free all related resources.

Parameters:

mixer

Mixer handle

int
snd_mixer_wait(
    snd_mixer_t* mixer,
    int timeout
)

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

Parameters:

mixer	Mixer handle
timeout	maximum time in milliseconds to wait

Returns:

0 otherwise a negative error code on failure

int
snd_mixer_set_compare(
    snd_mixer_t* mixer,
    snd_mixer_compare_t msort
)

Change mixer compare function and reorder elements.

Parameters:

mixer	Mixer handle
compare	Element compare function

Returns:

0 on success otherwise a negative error code

void
snd_mixer_set_callback(
    snd_mixer_t* obj,
    snd_mixer_callback_t val
)

Set callback function for a mixer.

Parameters:

obj	mixer handle
val	callback function

void*
snd_mixer_get_callback_private(const snd_mixer_t* obj)

Get callback private value for a mixer.

Parameters:

mixer

mixer handle

Returns:

callback private value

void
snd_mixer_set_callback_private(
    snd_mixer_t* obj,
    void* val
)

Set callback private value for a mixer.

Parameters:

mixer	mixer handle
val	callback private value

unsigned int
snd_mixer_get_count(const snd_mixer_t* obj)

Get elements count for a mixer.

Parameters:

mixer

mixer handle

Returns:

elements count

int
snd_mixer_class_unregister(snd_mixer_class_t* clss)

Unregister mixer element class and remove all its elements.

Note that the class structure is also deallocated!

Parameters:

class

Mixer element class

Returns:

0 on success otherwise a negative error code

snd_mixer_elem_t*
snd_mixer_elem_next(snd_mixer_elem_t* elem)

get next mixer element

Parameters:

elem	mixer element

Returns:

pointer to next element

snd_mixer_elem_t*
snd_mixer_elem_prev(snd_mixer_elem_t* elem)

get previous mixer element

Parameters:

elem	mixer element

Returns:

pointer to previous element

void
snd_mixer_elem_set_callback(
    snd_mixer_elem_t* obj,
    snd_mixer_elem_callback_t val
)

Set callback function for a mixer element.

Parameters:

mixer	mixer element
val	callback function

void*
snd_mixer_elem_get_callback_private(const snd_mixer_elem_t* obj)

Get callback private value for a mixer element.

Parameters:

mixer

mixer element

Returns:

callback private value

void
snd_mixer_elem_set_callback_private(
    snd_mixer_elem_t* obj,
    void* val
)

Set callback private value for a mixer element.

Parameters:

mixer	mixer element
val	callback private value

snd_mixer_elem_type_t
snd_mixer_elem_get_type(const snd_mixer_elem_t* obj)

Get type for a mixer element.

Parameters:

mixer

mixer element

Returns:

mixer element type

int
snd_mixer_class_register(
    snd_mixer_class_t* class_,
    snd_mixer_t* mixer
)

Register mixer element class.

For use by mixer element class specific code.

Parameters:

class	Mixer element class
mixer	Mixer handle

Returns:

0 on success otherwise a negative error code

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

Allocate a new mixer element.

For use by mixer element class specific code.

Parameters:

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

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_add(
    snd_mixer_elem_t* elem,
    snd_mixer_class_t* class_
)

Add an element for a registered mixer element class.

For use by mixer element class specific code.

Parameters:

elem	Mixer element
class	Mixer element class

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_remove(snd_mixer_elem_t* elem)

Remove a mixer element.

For use by mixer element class specific code.

Parameters:

elem	Mixer element

Returns:

0 on success otherwise a negative error code

void
snd_mixer_elem_free(snd_mixer_elem_t* elem)

Free a mixer element.

For use by mixer element class specific code.

Parameters:

elem	Mixer element

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_info(snd_mixer_elem_t* elem)

Mixer element informations are changed.

For use by mixer element class specific code.

Parameters:

elem	Mixer element

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_value(snd_mixer_elem_t* elem)

Mixer element values is changed.

For use by mixer element class specific code.

Parameters:

elem	Mixer element

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_attach(
    snd_mixer_elem_t* melem,
    snd_hctl_elem_t* helem
)

Attach an HCTL element to a mixer element.

For use by mixer element class specific code.

Parameters:

melem	Mixer element
helem	HCTL element

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_detach(
    snd_mixer_elem_t* melem,
    snd_hctl_elem_t* helem
)

Detach an HCTL element from a mixer element.

For use by mixer element class specific code.

Parameters:

melem	Mixer element
helem	HCTL element

Returns:

0 on success otherwise a negative error code

int
snd_mixer_elem_empty(snd_mixer_elem_t* melem)

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

For use by mixer element class specific code.

Parameters:

melem

Mixer element

Returns:

0 if not empty, 1 if empty

void*
snd_mixer_elem_get_private(const snd_mixer_elem_t* melem)

Get private data associated to give mixer element.

For use by mixer element class specific code.

Parameters:

elem	Mixer element

Returns:

private data

size_t
snd_mixer_class_sizeof(void)

get size of snd_mixer_class_t

Returns:

size in bytes

int
snd_mixer_class_malloc(snd_mixer_class_t** ptr)

allocate an invalid snd_mixer_class_t using standard malloc

Parameters:

ptr	returned pointer

Returns:

0 on success otherwise negative error code

void
snd_mixer_class_free(snd_mixer_class_t* obj)

frees a previously allocated snd_mixer_class_t

Parameters:

obj	pointer to object to free

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

copy one snd_mixer_class_t to another

Parameters:

dst	pointer to destination
src	pointer to source

snd_mixer_t*
snd_mixer_class_get_mixer(const snd_mixer_class_t* class_)

Get a mixer associated to given mixer class.

Parameters:

obj	Mixer simple class identifier

Returns:

mixer pointer

snd_mixer_event_t
snd_mixer_class_get_event(const snd_mixer_class_t* class_)

Get mixer event callback associated to given mixer class.

Parameters:

obj	Mixer simple class identifier

Returns:

event callback pointer

void*
snd_mixer_class_get_private(const snd_mixer_class_t* class_)

Get mixer private data associated to given mixer class.

Parameters:

obj	Mixer simple class identifier

Returns:

event callback pointer

snd_mixer_compare_t
snd_mixer_class_get_compare(const snd_mixer_class_t* class_)

Get mixer compare callback associated to given mixer class.

Parameters:

obj	Mixer simple class identifier

Returns:

event callback pointer

int
snd_mixer_class_set_event(
    snd_mixer_class_t* class_,
    snd_mixer_event_t event
)

Set mixer event callback to given mixer class.

Parameters:

obj	Mixer simple class identifier
event	Event callback

Returns:

zero if success, otherwise a negative error code

int
snd_mixer_class_set_private(
    snd_mixer_class_t* class_,
    void* private_data
)

Set mixer private data to given mixer class.

Parameters:

obj	Mixer simple class identifier
private_data	class private data

Returns:

zero if success, otherwise a negative error code

int
snd_mixer_class_set_private_free(
    snd_mixer_class_t* class_,
    void(*)(snd_mixer_class_t*) private_free
)

Set mixer private data free callback to given mixer class.

Parameters:

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

Returns:

zero if success, otherwise a negative error code

int
snd_mixer_class_set_compare(
    snd_mixer_class_t* class_,
    snd_mixer_compare_t compare
)

Set mixer compare callback to given mixer class.

Parameters:

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

Returns:

zero if success, otherwise a negative error code

Macros

#define snd_mixer_class_alloca(ptr)

allocate an invalid snd_mixer_class_t using standard alloca

Parameters:

ptr	returned pointer