ALSA project - the C library reference
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
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., 59 Temple Place, Suite 330, Boston, MA 02111-1307 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 
91 /*
92  * Use Case Verb.
93  *
94  * The use case verb is the main device audio action. e.g. the "HiFi" use
95  * case verb will configure the audio hardware for HiFi Music playback
96  * and capture.
97  */
98 #define SND_USE_CASE_VERB_INACTIVE "Inactive"
99 #define SND_USE_CASE_VERB_HIFI "HiFi"
100 #define SND_USE_CASE_VERB_HIFI_LOW_POWER "HiFi Low Power"
101 #define SND_USE_CASE_VERB_VOICE "Voice"
102 #define SND_USE_CASE_VERB_VOICE_LOW_POWER "Voice Low Power"
103 #define SND_USE_CASE_VERB_VOICECALL "Voice Call"
104 #define SND_USE_CASE_VERB_IP_VOICECALL "Voice Call IP"
105 #define SND_USE_CASE_VERB_ANALOG_RADIO "FM Analog Radio"
106 #define SND_USE_CASE_VERB_DIGITAL_RADIO "FM Digital Radio"
107 /* add new verbs to end of list */
108 
109 
110 /*
111  * Use Case Device.
112  *
113  * Physical system devices the render and capture audio. Devices can be OR'ed
114  * together to support audio on simultaneous devices.
115  */
116 #define SND_USE_CASE_DEV_NONE "None"
117 #define SND_USE_CASE_DEV_SPEAKER "Speaker"
118 #define SND_USE_CASE_DEV_LINE "Line"
119 #define SND_USE_CASE_DEV_HEADPHONES "Headphones"
120 #define SND_USE_CASE_DEV_HEADSET "Headset"
121 #define SND_USE_CASE_DEV_HANDSET "Handset"
122 #define SND_USE_CASE_DEV_BLUETOOTH "Bluetooth"
123 #define SND_USE_CASE_DEV_EARPIECE "Earpiece"
124 #define SND_USE_CASE_DEV_SPDIF "SPDIF"
125 #define SND_USE_CASE_DEV_HDMI "HDMI"
126 /* add new devices to end of list */
127 
128 
129 /*
130  * Use Case Modifiers.
131  *
132  * The use case modifier allows runtime configuration changes to deal with
133  * asynchronous events.
134  *
135  * e.g. to record a voice call :-
136  * 1. Set verb to SND_USE_CASE_VERB_VOICECALL (for voice call)
137  * 2. Set modifier SND_USE_CASE_MOD_CAPTURE_VOICE when capture required.
138  * 3. Call snd_use_case_get("CapturePCM") to get ALSA source PCM name
139  * with captured voice pcm data.
140  *
141  * e.g. to play a ring tone when listenin to MP3 Music :-
142  * 1. Set verb to SND_USE_CASE_VERB_HIFI (for MP3 playback)
143  * 2. Set modifier to SND_USE_CASE_MOD_PLAY_TONE when incoming call happens.
144  * 3. Call snd_use_case_get("PlaybackPCM") to get ALSA PCM sink name for
145  * ringtone pcm data.
146  */
147 #define SND_USE_CASE_MOD_CAPTURE_VOICE "Capture Voice"
148 #define SND_USE_CASE_MOD_CAPTURE_MUSIC "Capture Music"
149 #define SND_USE_CASE_MOD_PLAY_MUSIC "Play Music"
150 #define SND_USE_CASE_MOD_PLAY_VOICE "Play Voice"
151 #define SND_USE_CASE_MOD_PLAY_TONE "Play Tone"
152 #define SND_USE_CASE_MOD_ECHO_REF "Echo Reference"
153 /* add new modifiers to end of list */
154 
155 
164 #define SND_USE_CASE_TQ_MUSIC "Music"
165 #define SND_USE_CASE_TQ_VOICE "Voice"
166 #define SND_USE_CASE_TQ_TONES "Tones"
169 typedef struct snd_use_case_mgr snd_use_case_mgr_t;
170 
177 char *snd_use_case_identifier(const char *fmt, ...);
178 
185 int snd_use_case_free_list(const char *list[], int items);
186 
214  const char *identifier,
215  const char **list[]);
216 
217 
323  const char *identifier,
324  const char **value);
325 
338  const char *identifier,
339  long *value);
340 
364  const char *identifier,
365  const char *value);
366 
373 int snd_use_case_mgr_open(snd_use_case_mgr_t **uc_mgr, const char *card_name);
374 
375 
382 
389 
396 
397 /*
398  * helper functions
399  */
400 
406 static __inline__ int snd_use_case_card_list(const char **list[])
407 {
408  return snd_use_case_get_list(NULL, NULL, list);
409 }
410 
417 static __inline__ int snd_use_case_verb_list(snd_use_case_mgr_t *uc_mgr,
418  const char **list[])
419 {
420  return snd_use_case_get_list(uc_mgr, "_verbs", list);
421 }
422 
427 #ifdef __cplusplus
428 }
429 #endif
430 
431 #endif /* __ALSA_USE_CASE_H */