Use Case Interface

Overview

The ALSA Use Case manager interface. More…

// typedefs

typedef struct snd_use_case_mgr snd_use_case_mgr_t;

// global functions

char*
snd_use_case_identifier(
    const char* fmt,
    ...
);

int
snd_use_case_free_list(
    const char* list[],
    int items
);

int
snd_use_case_get_list(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char** list[]
);

int
snd_use_case_get(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char** value
);

int
snd_use_case_geti(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    long* value
);

int
snd_use_case_set(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char* value
);

int
snd_use_case_mgr_open(
    snd_use_case_mgr_t** uc_mgr,
    const char* card_name
);

int
snd_use_case_mgr_reload(snd_use_case_mgr_t* uc_mgr);

int
snd_use_case_mgr_close(snd_use_case_mgr_t* uc_mgr);

int
snd_use_case_mgr_reset(snd_use_case_mgr_t* uc_mgr);

static
__inline__ int
snd_use_case_card_list(const char** list[]);

static
__inline__ int
snd_use_case_verb_list(
    snd_use_case_mgr_t* uc_mgr,
    const char** list[]
);

// macros

#define SND_USE_CASE_DEV_BLUETOOTH
#define SND_USE_CASE_DEV_EARPIECE
#define SND_USE_CASE_DEV_HANDSET
#define SND_USE_CASE_DEV_HDMI
#define SND_USE_CASE_DEV_HEADPHONES
#define SND_USE_CASE_DEV_HEADSET
#define SND_USE_CASE_DEV_LINE
#define SND_USE_CASE_DEV_NONE
#define SND_USE_CASE_DEV_SPDIF
#define SND_USE_CASE_DEV_SPEAKER
#define SND_USE_CASE_MOD_CAPTURE_MUSIC
#define SND_USE_CASE_MOD_CAPTURE_VOICE
#define SND_USE_CASE_MOD_ECHO_REF
#define SND_USE_CASE_MOD_PLAY_MUSIC
#define SND_USE_CASE_MOD_PLAY_TONE
#define SND_USE_CASE_MOD_PLAY_VOICE
#define SND_USE_CASE_TQ_MUSIC
#define SND_USE_CASE_TQ_TONES
#define SND_USE_CASE_TQ_VOICE
#define SND_USE_CASE_VERB_ANALOG_RADIO
#define SND_USE_CASE_VERB_DIGITAL_RADIO
#define SND_USE_CASE_VERB_HIFI
#define SND_USE_CASE_VERB_HIFI_LOW_POWER
#define SND_USE_CASE_VERB_INACTIVE
#define SND_USE_CASE_VERB_IP_VOICECALL
#define SND_USE_CASE_VERB_VOICE
#define SND_USE_CASE_VERB_VOICECALL
#define SND_USE_CASE_VERB_VOICE_LOW_POWER

Detailed Documentation

The ALSA Use Case manager interface. See ALSA Use Case Interface page for more details.

Typedefs

typedef struct snd_use_case_mgr snd_use_case_mgr_t

use case container

Global Functions

char*
snd_use_case_identifier(
    const char* fmt,
    ...
)

Create an identifier.

Parameters:

fmt	Format (sprintf like)
…	Optional arguments for sprintf like format

Returns:

Allocated string identifier or NULL on error

int
snd_use_case_free_list(
    const char* list[],
    int items
)

Free a string list.

Parameters:

list	The string list to free
items	Count of strings

Returns:

Zero if success, otherwise a negative error code

int
snd_use_case_get_list(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char** list[]
)

Obtain a list of entries.

Defined identifiers:

• NULL - get card list (in pair cardname+comment)

• _verbs - get verb list (in pair verb+comment)

• _devices[/{verb}] - get list of supported devices (in pair device+comment)

• _modifiers[/{verb}] - get list of supported modifiers (in pair modifier+comment)

• TQ[/{verb}] - get list of TQ identifiers

• _enadevs - get list of enabled devices

• _enamods - get list of enabled modifiers

• _supporteddevs/{modifier}|{device}[/{verb}] - list of supported devices

• _conflictingdevs/{modifier}|{device}[/{verb}] - list of conflicting devices

Note that at most one of the supported/conflicting devs lists has any entries, and when neither is present, all devices are supported.

Parameters:

uc_mgr	Use case manager (may be NULL - card list)
identifier	(may be NULL - card list)
list	Returned allocated list
uc_mgr	Use case manager (may be NULL - card list)
identifier	(may be NULL - card list)
list	Returned allocated list

Returns:

Number of list entries if success, otherwise a negative error code

Number of list entries if success, otherwise a negative error code

int
snd_use_case_get(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char** value
)

Get current - string.

Note: The returned string is dynamically allocated, use free() to deallocate this string. (Yes, the value parameter shouldn’t be marked as “const”, but it’s too late to fix it, sorry about that.)

Known identifiers:

• NULL - return current card

• _verb - return current verb

• [=]{NAME}[/[{modifier}|{/device}][/{verb}]]

  • value identifier {NAME}

  • Search starts at given modifier or device if any, else at a verb

  • Search starts at given verb if any, else current verb

  • Searches modifier/device, then verb, then defaults

  • Specify a leading “=” to search only the exact device/modifier/verb specified, and not search through each object in turn.

  • Examples:

    • “PlaybackPCM/Play Music”

    • “CapturePCM/SPDIF”

    • From ValueDefaults only: “=Variable”

    • From current active verb: “=Variable//”

    • From verb “Verb”: “=Variable//Verb”

    • From “Modifier” in current active verb: “=Variable/Modifier/”

    • From “Modifier” in “Verb”: “=Variable/Modifier/Verb”

Recommended names for values:

• TQ

  • Tone Quality

• PlaybackPCM

  • full PCM playback device name

• PlaybackPCMIsDummy

  • Valid values: “yes” and “no”. If set to “yes”, the PCM named by the PlaybackPCM value is a dummy device, meaning that opening it enables an audio path in the hardware, but writing to the PCM device has no effect.

• CapturePCM

  • full PCM capture device name

• CapturePCMIsDummy

  • Valid values: “yes” and “no”. If set to “yes”, the PCM named by the CapturePCM value is a dummy device, meaning that opening it enables an audio path in the hardware, but reading from the PCM device has no effect.

• PlaybackRate

  • playback device sample rate

• PlaybackChannels

  • playback device channel count

• PlaybackCTL

  • playback control device name

• PlaybackVolume

  • playback control volume ID string

• PlaybackSwitch

  • playback control switch ID string

• CaptureRate

  • capture device sample rate

• CaptureChannels

  • capture device channel count

• CaptureCTL

  • capture control device name

• CaptureVolume

  • capture control volume ID string

• CaptureSwitch

  • capture control switch ID string

• PlaybackMixer

  • name of playback mixer

• PlaybackMixerID

  • mixer playback ID

• CaptureMixer

  • name of capture mixer

• CaptureMixerID

  • mixer capture ID

• JackControl, JackDev, JackHWMute

  • Jack information for a device. The jack status can be reported via a kcontrol and/or via an input device. JackControl is the kcontrol name of the jack, and JackDev is the input device id of the jack (if the full input device path is /dev/input/by-id/foo, the JackDev value should be “foo”). UCM configuration files should contain both JackControl and JackDev when possible, because applications are likely to support only one or the other.

    If JackHWMute is set, it indicates that when the jack is plugged in, the hardware automatically mutes some other device(s). The JackHWMute value is a space-separated list of device names (this isn’t compatible with device names with spaces in them, so don’t use such device names!). Note that JackHWMute should be used only when the hardware enforces the automatic muting. If the hardware doesn’t enforce any muting, it may still be tempting to set JackHWMute to trick upper software layers to e.g. automatically mute speakers when headphones are plugged in, but that’s application policy configuration that doesn’t belong to UCM configuration files.

Note: String is dynamically allocated, use free() to deallocate this string.

Parameters:

uc_mgr	Use case manager
identifier
value	Value pointer
uc_mgr	Use case manager
identifier
value	Value pointer

Returns:

Zero if success, otherwise a negative error code

Zero if success, otherwise a negative error code

int
snd_use_case_geti(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    long* value
)

Get current - integer.

Known identifiers:

• _devstatus/{device} - return status for given device

• _modstatus/{modifier} - return status for given modifier

Parameters:

uc_mgr	Use case manager
identifier
value	result
uc_mgr	Use case manager
identifier

Returns:

Zero if success, otherwise a negative error code

Value if success, otherwise a negative error code

int
snd_use_case_set(
    snd_use_case_mgr_t* uc_mgr,
    const char* identifier,
    const char* value
)

Set new.

Known identifiers:

• _verb - set current verb = value

• _enadev - enable given device = value

• _disdev - disable given device = value

• _swdev/{old_device} - new_device = value

  • disable old_device and then enable new_device

  • if old_device is not enabled just return

  • check transmit sequence firstly

• _enamod - enable given modifier = value

• _dismod - disable given modifier = value

• _swmod/{old_modifier} - new_modifier = value

  • disable old_modifier and then enable new_modifier

  • if old_modifier is not enabled just return

  • check transmit sequence firstly

Parameters:

uc_mgr	Use case manager
identifier
value	Value
uc_mgr	Use case manager
identifier
value	Value

Returns:

Zero if success, otherwise a negative error code

Zero if success, otherwise a negative error code

int
snd_use_case_mgr_open(
    snd_use_case_mgr_t** uc_mgr,
    const char* card_name
)

Open and initialise use case core for sound card.

Open and initialise use case core for sound card.

Parameters:

uc_mgr	Returned use case manager pointer
card_name	Sound card name.
uc_mgr	Returned use case manager pointer
card_name	name of card to open

Returns:

zero if success, otherwise a negative error code

zero on success, otherwise a negative error code

int
snd_use_case_mgr_reload(snd_use_case_mgr_t* uc_mgr)

Reload and re-parse use case configuration files for sound card.

Reload and re-parse use case configuration files for sound card.

Parameters:

uc_mgr	Use case manager
uc_mgr	Use case manager

Returns:

zero if success, otherwise a negative error code

zero on success, otherwise a negative error code

int
snd_use_case_mgr_close(snd_use_case_mgr_t* uc_mgr)

Close use case manager.

Parameters:

uc_mgr	Use case manager
uc_mgr	Use case manager

Returns:

zero if success, otherwise a negative error code

zero on success, otherwise a negative error code

int
snd_use_case_mgr_reset(snd_use_case_mgr_t* uc_mgr)

Reset use case manager verb, device, modifier to deafult settings.

Reset use case manager verb, device, modifier to deafult settings.

Parameters:

uc_mgr	Use case manager
uc_mgr	Use case manager

Returns:

zero if success, otherwise a negative error code

zero on success, otherwise a negative error code

static
__inline__ int
snd_use_case_card_list(const char** list[])

Obtain a list of cards.

Parameters:

list	Returned allocated list

Returns:

Number of list entries if success, otherwise a negative error code

static
__inline__ int
snd_use_case_verb_list(
    snd_use_case_mgr_t* uc_mgr,
    const char** list[]
)

Obtain a list of verbs.

Parameters:

uc_mgr	Use case manager
list	Returned list of verbs

Returns:

Number of list entries if success, otherwise a negative error code

Macros

#define SND_USE_CASE_DEV_BLUETOOTH

Bluetooth Device

#define SND_USE_CASE_DEV_EARPIECE

Earpiece Device

#define SND_USE_CASE_DEV_HANDSET

Handset Device

#define SND_USE_CASE_DEV_HDMI

HDMI Device

#define SND_USE_CASE_DEV_HEADPHONES

Headphones Device

#define SND_USE_CASE_DEV_HEADSET

Headset Device

#define SND_USE_CASE_DEV_LINE

Line Device

#define SND_USE_CASE_DEV_NONE

None Device

#define SND_USE_CASE_DEV_SPDIF

SPDIF Device

#define SND_USE_CASE_DEV_SPEAKER

Speaker Device

#define SND_USE_CASE_MOD_CAPTURE_MUSIC

Capture Music Modifier

#define SND_USE_CASE_MOD_CAPTURE_VOICE

Capture Voice Modifier

#define SND_USE_CASE_MOD_ECHO_REF

Echo Reference Modifier

#define SND_USE_CASE_MOD_PLAY_MUSIC

Play Music Modifier

#define SND_USE_CASE_MOD_PLAY_TONE

Play Tone Modifier

#define SND_USE_CASE_MOD_PLAY_VOICE

Play Voice Modifier

#define SND_USE_CASE_TQ_MUSIC

TQ - Tone Quality

The interface allows clients to determine the audio TQ required for each use case verb and modifier. It’s intended as an optional hint to the audio driver in order to lower power consumption.Music Tone Quality

#define SND_USE_CASE_TQ_TONES

Tones Tone Quality

#define SND_USE_CASE_TQ_VOICE

Voice Tone Quality

#define SND_USE_CASE_VERB_ANALOG_RADIO

FM Analog Radio Verb

#define SND_USE_CASE_VERB_DIGITAL_RADIO

FM Digital Radio Verb

#define SND_USE_CASE_VERB_HIFI

HiFi Verb

#define SND_USE_CASE_VERB_HIFI_LOW_POWER

HiFi Low Power Verb

#define SND_USE_CASE_VERB_INACTIVE

Inactive Verb

#define SND_USE_CASE_VERB_IP_VOICECALL

Voice Call IP Verb

#define SND_USE_CASE_VERB_VOICE

Voice Verb

#define SND_USE_CASE_VERB_VOICECALL

Voice Call Verb

#define SND_USE_CASE_VERB_VOICE_LOW_POWER

Voice Low Power Verb