ascenario: Fix function declaration changes
[alsa-lib.git] / include / ascenario.h
1 /**
2  * \file include/ascenario.h
3  * \brief Scenario interface for the ALSA driver
4  * \author Liam Girdwood <lrg@slimlogic.co.uk>
5  * \author Stefan Schmidt <stefan@slimlogic.co.uk>
6  * \author Jaroslav Kysela <perex@perex.cz>
7  * \date 2008-2009
8  */
9 /*
10  *
11  *   This library is free software; you can redistribute it and/or modify
12  *   it under the terms of the GNU Lesser General Public License as
13  *   published by the Free Software Foundation; either version 2.1 of
14  *   the License, or (at your option) any later version.
15  *
16  *   This program is distributed in the hope that it will be useful,
17  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
18  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  *   GNU Lesser General Public License for more details.
20  *
21  *   You should have received a copy of the GNU Lesser General Public
22  *   License along with this library; if not, write to the Free Software
23  *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
24  *
25  *  Copyright (C) 2008-2009 SlimLogic Ltd
26  */
27
28 #ifndef __ALSA_ASCENARIO_H
29 #define __ALSA_ASCENARIO_H
30
31 /*! \page ascenario Scenario interface
32
33 It allows switching audio settings between scenarios or uses-cases like
34 listening to music and answering an incoming phone call. Made of control
35 aliasing for playback, capture master and switch as well as the option to
36 post- and prefix a sequence of control changes avoiding pops and other
37 unwanted noise.
38
39 */
40
41 #ifdef __cplusplus
42 extern "C" {
43 #endif
44
45 /**
46  *  \defgroup AScenario Scenario Interface
47  *  The ALSA scenario interface.
48  *  See \ref ascenario page for more details.
49  *  \{
50  */
51      
52 /**
53  * Scenario IDs
54  *
55  * Standard Scenario IDs - Add new scenarios at the end.
56  */
57
58 /** use main speaker for playback */
59 #define SND_SCN_PLAYBACK_SPEAKER        "playback speaker"
60 /** use headphone output for playback */
61 #define SND_SCN_PLAYBACK_HEADPHONES     "playback headphone"
62 /** use headset for playback */
63 #define SND_SCN_PLAYBACK_HEADSET        "playback headset"
64 /** use bluetooth interface for playback */
65 #define SND_SCN_PLAYBACK_BLUETOOTH      "playback bluetooth"
66 /** use handset interface for playback */
67 #define SND_SCN_PLAYBACK_HANDSET        "playback handset"
68 /** use gsm interface for playback */
69 #define SND_SCN_PLAYBACK_GSM            "playback gsm"
70 /** use line interface for playback */
71 #define SND_SCN_PLAYBACK_LINE           "playback line"
72
73 /** use mic input for capture */
74 #define SND_SCN_CAPTURE_MIC             "capture mic"
75 /** use line input for capture */
76 #define SND_SCN_CAPTURE_LINE            "capture line"
77 /** use headset input for capture */
78 #define SND_SCN_CAPTURE_HEADSET         "capture headset"
79 /** use handset input for capture */
80 #define SND_SCN_CAPTURE_HANDSET         "capture handset"
81 /** use bluetooth input for capture */
82 #define SND_SCN_CAPTURE_BLUETOOTH       "capture bluetooth"
83 /** use gsm input for capture */
84 #define SND_SCN_CAPTURE_GSM             "capture gsm"
85
86 /** phone call through gsm handset */
87 #define SND_SCN_PHONECALL_GSM_HANDSET   "phonecall gsm handset"
88 /** phone call through bluetooth handset */
89 #define SND_SCN_PHONECALL_BT_HANDSET    "phonecall bt handset"
90 /** phone call through ip handset */
91 #define SND_SCN_PHONECALL_IP_HANDSET    "phonecall ip handset"
92 /** phone call through gsm headset */
93 #define SND_SCN_PHONECALL_GSM_HEADSET   "phonecall gsm headset"
94 /** phone call through bluetooth headset */
95 #define SND_SCN_PHONECALL_BT_HEADSET    "phonecall bt headset"
96 /** phone call through ip headset */
97 #define SND_SCN_PHONECALL_IP_HEADSET    "phonecall ip headset"
98
99 /**
100  * QOS
101  *
102  * Defines Audio Quality of Service. Systems supporting different types of QoS
103  * often have lower power consumption on lower quality levels.
104  */
105 /** use HIFI grade QoS service */
106 #define SND_POWER_QOS_HIFI                      0
107 /** use voice grade QoS service */
108 #define SND_POWER_QOS_VOICE                     1
109 /** use system sound grade QoS service */
110 #define SND_POWER_QOS_SYSTEM                    2
111
112 /**
113  * KControl types
114  */
115 /** master playback volume */
116 #define SND_SCN_KCTL_MASTER_PLAYBACK_VOLUME     1
117 /** master playback switch */
118 #define SND_SCN_KCTL_MASTER_PLAYBACK_SWITCH     2
119 /** master capture volume */
120 #define SND_SCN_KCTL_MASTER_CAPTURE_VOLUME      3
121 /** master capture switch */
122 #define SND_SCN_KCTL_MASTER_CAPTURE_SWITCH      4
123
124 /**
125  * Integer types
126  */
127 /** QoS volume */
128 #define SND_SCN_INT_QOS                         1
129
130 /** Scenario container */
131 typedef struct snd_scenario snd_scenario_t;
132
133 /* TODO: add notification */
134
135 /**
136  * \brief list supported scenarios for given soundcard
137  * \param scn scenario
138  * \param list returned list of supported scenario names
139  * \return number of scenarios if success, otherwise a negative error code
140  */
141 int snd_scenario_list(snd_scenario_t *scn, const char **list[]);
142
143 /**
144  * \brief set new scenario for sound card
145  * \param scn scenario
146  * \param scenario scenario id string
147  * \return zero if success, otherwise a negative error code
148  */
149 int snd_scenario_set_scn(snd_scenario_t *scn, const char *scenario);
150
151 /**
152  * \brief get scenario
153  * \param scn scenario
154  * \return scenario id string
155  *
156  * Get current sound card scenario.
157  */
158 const char *snd_scenario_get_scn(snd_scenario_t *scn);
159
160 /**
161  * \brief get associated control id
162  * \param scn scenario
163  * \param kctl_type see SND_SCN_KCTL_* constants
164  * \param id returned control id
165  * \return zero if success, otherwise a negative error code
166  *
167  * Get the control id for the current scenario.
168  */
169 int snd_scenario_get_kcontrol(snd_scenario_t *scn,
170                               int kctl_type, snd_ctl_elem_id_t *id);
171
172 /**
173  * \brief set integer value
174  * \param scn scenario
175  * \param int_key see SND_SCN_INT_* constants
176  * \param value value
177  * \return zero if success, otherwise a negative error code
178  */
179 int snd_scenario_set_integer(snd_scenario_t *scn, int int_key, int value);
180
181 /**
182  * \brief get integer value
183  * \param scn scenario
184  * \param int_key see SND_SCN_INT_* constants
185  * \param value value
186  * \return zero if success, otherwise a negative error code
187  */
188 int snd_scenario_get_integer(snd_scenario_t *scn, int int_key, int *value);
189
190 /**
191  * \brief open scenario core for sound card
192  * \param card_name sound card name.
193  * \return zero if success, otherwise a negative error code
194  */
195 snd_scenario_t *snd_scenario_open(const char *card_name);
196
197 /**
198  * \brief reload and reparse scenario configuration
199  * \param scn scenario
200  * \return zero if success, otherwise a negative error code
201  */
202 int snd_scenario_reload(snd_scenario_t *scn);
203
204 /**
205  * \brief close scenario
206  * \param scn scenario
207  * \return zero if success, otherwise a negative error code
208  */
209 int snd_scenario_close(snd_scenario_t *scn);
210
211 /**
212  * \brief dump scenario
213  * \param output handle
214  * \param card_name sound card name
215  * \return zero if success, otherwise a negative error code
216  */
217 int snd_scenario_dump(snd_output_t *output, const char *card_name);
218
219 /**
220  *  \}
221  */
222
223 #ifdef __cplusplus
224 }
225 #endif
226
227 #endif /* __ALSA_ASCENARIO_H */