Mixer Interface

Overview

The mixer interface. Moreā€¦

// typedefs

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

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

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