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 */