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 /* add new devices to end of list */
145 
146 
147 /*
148  * Use Case Modifiers.
149  *
150  * The use case modifier allows runtime configuration changes to deal with
151  * asynchronous events.
152  *
153  * If multiple modifiers with the same name exists, the number suffixes should
154  * be added to these names like 'Echo Reference 1','Echo Reference 2' etc.
155  * No number gaps are allowed. The names with numbers must be continuous.
156  * It is allowed to put a whitespace between name and index for the better
157  * readability. The modifier names 'Something 1' and 'Something1' are equal
158  * for this purpose.
159  *
160  * e.g. to record a voice call :-
161  * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
162  * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
163  * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
164  * with captured voice pcm data.
165  *
166  * e.g. to play a ring tone when listenin to MP3 Music :-
167  * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
168  * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
169  * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
170  * ringtone pcm data.
171  */
172 #define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice"
173 #define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music"
174 #define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music"
175 #define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice"
176 #define SND_USE_CASE_MOD_PLAY_TONE "Play Tone"
177 #define SND_USE_CASE_MOD_ECHO_REF "Echo Reference"
178 /* add new modifiers to end of list */
179 
180 
189 #define SND_USE_CASE_TQ_MUSIC "Music"
190 #define SND_USE_CASE_TQ_VOICE "Voice"
191 #define SND_USE_CASE_TQ_TONES "Tones"
194 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
195 
202 char *snd_use_case_identifier(const char *fmt, ...);
203 
210 int snd_use_case_free_list(const char *list[], int items);
211 
241  const char *identifier,
242  const char **list[]);
243 
244 
397  const char *identifier,
398  const char **value);
399 
412  const char *identifier,
413  long *value);
414 
443  const char *identifier,
444  const char *value);
445 
469  const char *card_name);
470 
471 
478 
485 
492 
493 /*
494  * helper functions
495  */
496 
502 static __inline__ int snd_use_case_card_list(const char **list[])
503 {
504  return snd_use_case_get_list(NULL, NULL, list);
505 }
506 
513 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
514  const char **list[])
515 {
516  return snd_use_case_get_list(uc_mgr, "_verbs", list);
517 }
518 
527  const char *ucm_id,
528  const char *value);
529 
538  const char *ucm_id,
539  const char *value);
540 
545 #ifdef __cplusplus
546 }
547 #endif
548 
549 #endif /* __ALSA_USE_CASE_H */
char * snd_use_case_identifier(const char *fmt,...)
Create an identifier.
Definition: main.c:117
int snd_use_case_free_list(const char *list[], int items)
Free a string list.
Definition: main.c:142
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:1430
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:2674
struct _snd_ctl_elem_id snd_ctl_elem_id_t
Definition: control.h:57
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:1511
int snd_use_case_geti(snd_use_case_mgr_t *uc_mgr, const char *identifier, long *value)
Get current - integer.
Definition: main.c:2273
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:1365
struct snd_use_case_mgr snd_use_case_mgr_t
Definition: use-case.h:194
int snd_use_case_set(snd_use_case_mgr_t *uc_mgr, const char *identifier, const char *value)
Set new.
Definition: main.c:2585
struct _snd_mixer_selem_id snd_mixer_selem_id_t
Definition: mixer.h:219
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:2642
int snd_use_case_mgr_close(snd_use_case_mgr_t *uc_mgr)
Close use case manager.
Definition: main.c:1457
int snd_use_case_get(snd_use_case_mgr_t *uc_mgr, const char *identifier, const char **value)
Get current - string.
Definition: main.c:2173
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:1953