ALSA project - the C library reference

use-case.h
Go to the documentation of this file.
1
10/*
11 *
12 * This library is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Lesser General Public License as
14 * published by the Free Software Foundation; either version 2.1 of
15 * the License, or (at your option) any later version.
16 *
17 * This program is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Lesser General Public License for more details.
21 *
22 * You should have received a copy of the GNU Lesser General Public
23 * License along with this library; if not, write to the Free Software
24 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
25 *
26 * Copyright (C) 2008-2010 SlimLogic Ltd
27 * Copyright (C) 2010 Wolfson Microelectronics PLC
28 * Copyright (C) 2010 Texas Instruments Inc.
29 *
30 * Support for the verb/device/modifier core logic and API,
31 * command line tool and file parser was kindly sponsored by
32 * Texas Instruments Inc.
33 * Support for multiple active modifiers and devices,
34 * transition sequences, multiple client access and user defined use
35 * cases was kindly sponsored by Wolfson Microelectronics PLC.
36 */
37
38#ifndef __ALSA_USE_CASE_H
39#define __ALSA_USE_CASE_H
40
41#ifdef __cplusplus
42 extern "C" {
43#endif
44
45#include <alsa/asoundlib.h>
46
93/*
94 * Use Case Verb.
95 *
96 * The use case verb is the main device audio action. e.g. the "HiFi" use
97 * case verb will configure the audio hardware for HiFi Music playback
98 * and capture.
99 */
100#define SND_USE_CASE_VERB_INACTIVE "Inactive"
101#define SND_USE_CASE_VERB_HIFI "HiFi"
102#define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power"
103#define SND_USE_CASE_VERB_VOICE "Voice"
104#define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power"
105#define SND_USE_CASE_VERB_VOICECALL "Voice Call"
106#define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP"
107#define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio"
108#define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio"
109/* add new verbs to end of list */
110
111
112/*
113 * Use Case Device.
114 *
115 * Physical system devices the render and capture audio. Devices can be OR'ed
116 * together to support audio on simultaneous devices.
117 *
118 * If multiple devices with the same name exists, the number suffixes should
119 * be added to these names like HDMI1,HDMI2,HDMI3 etc. No number gaps are
120 * allowed. The names with numbers must be continuous. It is allowed to put
121 * a whitespace between name and index (like 'Line 1') for the better
122 * readability. The device names 'Line 1' and 'Line1' are equal for
123 * this purpose.
124 *
125 * If EnableSequence/DisableSequence controls independent paths in the hardware
126 * it is also recommended to split playback and capture UCM devices and use
127 * the number suffixes. Example use case: Use the integrated microphone
128 * in the laptop instead the microphone in headphones.
129 *
130 * The preference of the devices is determined by the priority value.
131 */
132#define SND_USE_CASE_DEV_NONE "None"
133#define SND_USE_CASE_DEV_SPEAKER "Speaker"
134#define SND_USE_CASE_DEV_LINE "Line"
135#define SND_USE_CASE_DEV_MIC "Mic"
136#define SND_USE_CASE_DEV_HEADPHONES "Headphones"
137#define SND_USE_CASE_DEV_HEADSET "Headset"
138#define SND_USE_CASE_DEV_HANDSET "Handset"
139#define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth"
140#define SND_USE_CASE_DEV_EARPIECE "Earpiece"
141#define SND_USE_CASE_DEV_SPDIF "SPDIF"
142#define SND_USE_CASE_DEV_HDMI "HDMI"
143#define SND_USE_CASE_DEV_USB "USB"
144#define SND_USE_CASE_DEV_DIRECT "Direct"
145/* add new devices to end of list */
146
147
148/*
149 * Use Case Modifiers.
150 *
151 * The use case modifier allows runtime configuration changes to deal with
152 * asynchronous events.
153 *
154 * If multiple modifiers with the same name exists, the number suffixes should
155 * be added to these names like 'Echo Reference 1','Echo Reference 2' etc.
156 * No number gaps are allowed. The names with numbers must be continuous.
157 * It is allowed to put a whitespace between name and index for the better
158 * readability. The modifier names 'Something 1' and 'Something1' are equal
159 * for this purpose.
160 *
161 * e.g. to record a voice call :-
162 * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
163 * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
164 * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
165 * with captured voice pcm data.
166 *
167 * e.g. to play a ring tone when listenin to MP3 Music :-
168 * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
169 * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
170 * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
171 * ringtone pcm data.
172 */
173#define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice"
174#define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music"
175#define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music"
176#define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice"
177#define SND_USE_CASE_MOD_PLAY_TONE "Play Tone"
178#define SND_USE_CASE_MOD_ECHO_REF "Echo Reference"
179/* add new modifiers to end of list */
180
181
190#define SND_USE_CASE_TQ_MUSIC "Music"
191#define SND_USE_CASE_TQ_VOICE "Voice"
192#define SND_USE_CASE_TQ_TONES "Tones"
195 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
196
203 char *snd_use_case_identifier(const char *fmt, ...);
204
211 int snd_use_case_free_list(const char *list[], int items);
212
241 int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr,
242 const char *identifier,
243 const char **list[]);
244
245
409 int snd_use_case_get(snd_use_case_mgr_t *uc_mgr,
410 const char *identifier,
411 const char **value);
412
424 int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr,
425 const char *identifier,
426 long *value);
427
455 int snd_use_case_set(snd_use_case_mgr_t *uc_mgr,
456 const char *identifier,
457 const char *value);
458
481 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr,
482 const char *card_name);
483
484
490 int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr);
491
497 int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr);
498
504 int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr);
505
506/*
507 * helper functions
508 */
509
515 static __inline__ int snd_use_case_card_list(const char **list[])
516{
517 return snd_use_case_get_list(NULL, NULL, list);
518}
519
526 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
527 const char **list[])
528{
529 return snd_use_case_get_list(uc_mgr, "_verbs", list);
530}
531
539 int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst,
540 const char *ucm_id,
541 const char *value);
542
550 int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst,
551 const char *ucm_id,
552 const char *value);
553
558#ifdef __cplusplus
559}
560#endif
561
562#endif /* __ALSA_USE_CASE_H */
snd_ctl_elem_id_t
struct _snd_ctl_elem_id snd_ctl_elem_id_t
Definition: control.h:82
snd_mixer_selem_id_t
struct _snd_mixer_selem_id snd_mixer_selem_id_t
Definition: mixer.h:219
snd_use_case_free_list
int snd_use_case_free_list(const char *list[], int items)
Free a string list.
Definition: main.c:153
snd_use_case_mgr_reset
int snd_use_case_mgr_reset(snd_use_case_mgr_t *uc_mgr)
Reset use case manager verb, device, modifier to deafult settings.
Definition: main.c:1647
snd_use_case_identifier
char * snd_use_case_identifier(const char *fmt,...)
Create an identifier.
Definition: main.c:128
snd_use_case_geti
int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr, const char *identifier, long *value)
Get current - integer.
Definition: main.c:2409
snd_use_case_mgr_open
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.
Definition: main.c:1495
snd_use_case_get
int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, const char *identifier, const char **value)
Get current - string.
Definition: main.c:2309
snd_use_case_get_list
int snd_use_case_get_list(snd_use_case_mgr_t *uc_mgr, const char *identifier, const char **list[])
Obtain a list of entries.
Definition: main.c:2089
snd_use_case_mgr_close
int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr)
Close use case manager.
Definition: main.c:1593
snd_use_case_parse_ctl_elem_id
int snd_use_case_parse_ctl_elem_id(snd_ctl_elem_id_t *dst, const char *ucm_id, const char *value)
Parse control element identifier.
Definition: main.c:2781
snd_use_case_mgr_t
struct snd_use_case_mgr snd_use_case_mgr_t
Definition: use-case.h:195
snd_use_case_set
int snd_use_case_set(snd_use_case_mgr_t *uc_mgr, const char *identifier, const char *value)
Set new.
Definition: main.c:2724
snd_use_case_parse_selem_id
int snd_use_case_parse_selem_id(snd_mixer_selem_id_t *dst, const char *ucm_id, const char *value)
Parse mixer element identifier.
Definition: main.c:2813
snd_use_case_mgr_reload
int snd_use_case_mgr_reload(snd_use_case_mgr_t *uc_mgr)
Reload and re-parse use case configuration files for sound card.
Definition: main.c:1566