|
char * | snd_use_case_identifier (const char *fmt,...) |
| Create an identifier. More...
|
|
int | snd_use_case_free_list (const char *list[], int items) |
| Free a string list. More...
|
|
int | snd_use_case_get_list (snd_use_case_mgr_t *uc_mgr, const char *identifier, const char **list[]) |
| Obtain a list of entries. More...
|
|
int | snd_use_case_get (snd_use_case_mgr_t *uc_mgr, const char *identifier, const char **value) |
| Get current - string. More...
|
|
int | snd_use_case_geti (snd_use_case_mgr_t *uc_mgr, const char *identifier, long *value) |
| Get current - integer. More...
|
|
int | snd_use_case_set (snd_use_case_mgr_t *uc_mgr, const char *identifier, const char *value) |
| Set new. More...
|
|
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. More...
|
|
int | snd_use_case_mgr_reload (snd_use_case_mgr_t *uc_mgr) |
| Reload and re-parse use case configuration files for sound card. More...
|
|
int | snd_use_case_mgr_close (snd_use_case_mgr_t *uc_mgr) |
| Close use case manager. More...
|
|
int | snd_use_case_mgr_reset (snd_use_case_mgr_t *uc_mgr) |
| Reset use case manager verb, device, modifier to deafult settings. More...
|
|
The use case manager works by configuring the sound card ALSA kcontrols to change the hardware digital and analog audio routing to match the requested device use case. The use case manager kcontrol configurations are stored in easy to modify text files.An audio use case can be defined by a verb and device parameter. The verb describes the use case action i.e. a phone call, listening to music, recording a conversation etc. The device describes the physical audio capture and playback hardware i.e. headphones, phone handset, bluetooth headset, etc.It's intended clients will mostly only need to set the use case verb and device for each system use case change (as the verb and device parameters cover most audio use cases).However there are times when a use case has to be modified at runtime. e.g.
- Incoming phone call when the device is playing music
- Recording sections of a phone call
- Playing tones during a call.
In order to allow asynchronous runtime use case adaptations, we have a third optional modifier parameter that can be used to further configure the use case during live audio runtime.This interface allows clients to :-
- Query the supported use case verbs, devices and modifiers for the machine.
- Set and Get use case verbs, devices and modifiers for the machine.
- Get the ALSA PCM playback and capture device PCMs for use case verb, use case device and modifier.
- Get the TQ parameter for each use case verb, use case device and modifier.
- Get the ALSA master playback and capture volume/switch kcontrols for each use case.
int snd_use_case_get |
( |
snd_use_case_mgr_t * |
uc_mgr, |
|
|
const char * |
identifier, |
|
|
const char ** |
value |
|
) |
| |
Get current - string.
- Parameters
-
uc_mgr | Use case manager |
identifier | |
value | Value pointer |
- Returns
- Zero if success, otherwise a negative error code
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
- 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
- PlaybackMixerID
- CaptureMixer
- CaptureMixerID
- 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.
- Parameters
-
uc_mgr | Use case manager |
identifier | |
value | Value pointer |
- Returns
- Zero if success, otherwise a negative error code
Note: String is dynamically allocated, use free() to deallocate this string.
int snd_use_case_get_list |
( |
snd_use_case_mgr_t * |
uc_mgr, |
|
|
const char * |
identifier, |
|
|
const char ** |
list[] |
|
) |
| |
Obtain a list of entries.
- Parameters
-
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
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 |
- Returns
- Number of list entries if success, otherwise a negative error code