1 /** 2 * \file include/mixer.h 3 * \brief Application interface library for the ALSA driver 4 * \author Jaroslav Kysela <perex@perex.cz> 5 * \author Abramo Bagnara <abramo@alsa-project.org> 6 * \author Takashi Iwai <tiwai@suse.de> 7 * \date 1998-2001 8 * 9 * Application interface library for the ALSA driver 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 */ 27 28 #ifndef __ALSA_MIXER_H 29 #define __ALSA_MIXER_H 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * \defgroup Mixer Mixer Interface 37 * The mixer interface. 38 * \{ 39 */ 40 41 /** Mixer handle */ 42 typedef struct _snd_mixer snd_mixer_t; 43 /** Mixer elements class handle */ 44 typedef struct _snd_mixer_class snd_mixer_class_t; 45 /** Mixer element handle */ 46 typedef struct _snd_mixer_elem snd_mixer_elem_t; 47 48 /** 49 * \brief Mixer callback function 50 * \param mixer Mixer handle 51 * \param mask event mask 52 * \param elem related mixer element (if any) 53 * \return 0 on success otherwise a negative error code 54 */ 55 typedef int (*snd_mixer_callback_t)(snd_mixer_t *ctl, 56 unsigned int mask, 57 snd_mixer_elem_t *elem); 58 59 /** 60 * \brief Mixer element callback function 61 * \param elem Mixer element 62 * \param mask event mask 63 * \return 0 on success otherwise a negative error code 64 */ 65 typedef int (*snd_mixer_elem_callback_t)(snd_mixer_elem_t *elem, 66 unsigned int mask); 67 68 /** 69 * \brief Compare function for sorting mixer elements 70 * \param e1 First element 71 * \param e2 Second element 72 * \return -1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2 73 */ 74 typedef int (*snd_mixer_compare_t)(const snd_mixer_elem_t *e1, 75 const snd_mixer_elem_t *e2); 76 77 /** 78 * \brief Event callback for the mixer class 79 * \param class_ Mixer class 80 * \param mask Event mask (SND_CTL_EVENT_*) 81 * \param helem HCTL element which invoked the event 82 * \param melem Mixer element associated to HCTL element 83 * \return zero if success, otherwise a negative error value 84 */ 85 typedef int (*snd_mixer_event_t)(snd_mixer_class_t *class_, unsigned int mask, 86 snd_hctl_elem_t *helem, snd_mixer_elem_t *melem); 87 88 89 /** Mixer element type */ 90 typedef enum _snd_mixer_elem_type { 91 /* Simple mixer elements */ 92 SND_MIXER_ELEM_SIMPLE, 93 SND_MIXER_ELEM_LAST = SND_MIXER_ELEM_SIMPLE 94 } snd_mixer_elem_type_t; 95 96 int snd_mixer_open(snd_mixer_t **mixer, int mode); 97 int snd_mixer_close(snd_mixer_t *mixer); 98 snd_mixer_elem_t *snd_mixer_first_elem(snd_mixer_t *mixer); 99 snd_mixer_elem_t *snd_mixer_last_elem(snd_mixer_t *mixer); 100 int snd_mixer_handle_events(snd_mixer_t *mixer); 101 int snd_mixer_attach(snd_mixer_t *mixer, const char *name); 102 int snd_mixer_attach_hctl(snd_mixer_t *mixer, snd_hctl_t *hctl); 103 int snd_mixer_detach(snd_mixer_t *mixer, const char *name); 104 int snd_mixer_detach_hctl(snd_mixer_t *mixer, snd_hctl_t *hctl); 105 int snd_mixer_get_hctl(snd_mixer_t *mixer, const char *name, snd_hctl_t **hctl); 106 int snd_mixer_poll_descriptors_count(snd_mixer_t *mixer); 107 int snd_mixer_poll_descriptors(snd_mixer_t *mixer, struct pollfd *pfds, unsigned int space); 108 int snd_mixer_poll_descriptors_revents(snd_mixer_t *mixer, struct pollfd *pfds, unsigned int nfds, unsigned short *revents); 109 int snd_mixer_load(snd_mixer_t *mixer); 110 void snd_mixer_free(snd_mixer_t *mixer); 111 int snd_mixer_wait(snd_mixer_t *mixer, int timeout); 112 int snd_mixer_set_compare(snd_mixer_t *mixer, snd_mixer_compare_t msort); 113 void snd_mixer_set_callback(snd_mixer_t *obj, snd_mixer_callback_t val); 114 void * snd_mixer_get_callback_private(const snd_mixer_t *obj); 115 void snd_mixer_set_callback_private(snd_mixer_t *obj, void * val); 116 unsigned int snd_mixer_get_count(const snd_mixer_t *obj); 117 int snd_mixer_class_unregister(snd_mixer_class_t *clss); 118 119 snd_mixer_elem_t *snd_mixer_elem_next(snd_mixer_elem_t *elem); 120 snd_mixer_elem_t *snd_mixer_elem_prev(snd_mixer_elem_t *elem); 121 void snd_mixer_elem_set_callback(snd_mixer_elem_t *obj, snd_mixer_elem_callback_t val); 122 void * snd_mixer_elem_get_callback_private(const snd_mixer_elem_t *obj); 123 void snd_mixer_elem_set_callback_private(snd_mixer_elem_t *obj, void * val); 124 snd_mixer_elem_type_t snd_mixer_elem_get_type(const snd_mixer_elem_t *obj); 125 126 int snd_mixer_class_register(snd_mixer_class_t *class_, snd_mixer_t *mixer); 127 int snd_mixer_elem_new(snd_mixer_elem_t **elem, 128 snd_mixer_elem_type_t type, 129 int compare_weight, 130 void *private_data, 131 void (*private_free)(snd_mixer_elem_t *elem)); 132 int snd_mixer_elem_add(snd_mixer_elem_t *elem, snd_mixer_class_t *class_); 133 int snd_mixer_elem_remove(snd_mixer_elem_t *elem); 134 void snd_mixer_elem_free(snd_mixer_elem_t *elem); 135 int snd_mixer_elem_info(snd_mixer_elem_t *elem); 136 int snd_mixer_elem_value(snd_mixer_elem_t *elem); 137 int snd_mixer_elem_attach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem); 138 int snd_mixer_elem_detach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem); 139 int snd_mixer_elem_empty(snd_mixer_elem_t *melem); 140 void *snd_mixer_elem_get_private(const snd_mixer_elem_t *melem); 141 142 size_t snd_mixer_class_sizeof(void); 143 /** \hideinitializer 144 * \brief allocate an invalid #snd_mixer_class_t using standard alloca 145 * \param ptr returned pointer 146 */ 147 #define snd_mixer_class_alloca(ptr) __snd_alloca(ptr, snd_mixer_class) 148 int snd_mixer_class_malloc(snd_mixer_class_t **ptr); 149 void snd_mixer_class_free(snd_mixer_class_t *obj); 150 void snd_mixer_class_copy(snd_mixer_class_t *dst, const snd_mixer_class_t *src); 151 snd_mixer_t *snd_mixer_class_get_mixer(const snd_mixer_class_t *class_); 152 snd_mixer_event_t snd_mixer_class_get_event(const snd_mixer_class_t *class_); 153 void *snd_mixer_class_get_private(const snd_mixer_class_t *class_); 154 snd_mixer_compare_t snd_mixer_class_get_compare(const snd_mixer_class_t *class_); 155 int snd_mixer_class_set_event(snd_mixer_class_t *class_, snd_mixer_event_t event); 156 int snd_mixer_class_set_private(snd_mixer_class_t *class_, void *private_data); 157 int snd_mixer_class_set_private_free(snd_mixer_class_t *class_, void (*private_free)(snd_mixer_class_t *)); 158 int snd_mixer_class_set_compare(snd_mixer_class_t *class_, snd_mixer_compare_t compare); 159 160 /** 161 * \defgroup SimpleMixer Simple Mixer Interface 162 * \ingroup Mixer 163 * The simple mixer interface. 164 * \{ 165 */ 166 167 /* Simple mixer elements API */ 168 169 /** Mixer simple element channel identifier */ 170 typedef enum _snd_mixer_selem_channel_id { 171 /** Unknown */ 172 SND_MIXER_SCHN_UNKNOWN = -1, 173 /** Front left */ 174 SND_MIXER_SCHN_FRONT_LEFT = 0, 175 /** Front right */ 176 SND_MIXER_SCHN_FRONT_RIGHT, 177 /** Rear left */ 178 SND_MIXER_SCHN_REAR_LEFT, 179 /** Rear right */ 180 SND_MIXER_SCHN_REAR_RIGHT, 181 /** Front center */ 182 SND_MIXER_SCHN_FRONT_CENTER, 183 /** Woofer */ 184 SND_MIXER_SCHN_WOOFER, 185 /** Side Left */ 186 SND_MIXER_SCHN_SIDE_LEFT, 187 /** Side Right */ 188 SND_MIXER_SCHN_SIDE_RIGHT, 189 /** Rear Center */ 190 SND_MIXER_SCHN_REAR_CENTER, 191 SND_MIXER_SCHN_LAST = 31, 192 /** Mono (Front left alias) */ 193 SND_MIXER_SCHN_MONO = SND_MIXER_SCHN_FRONT_LEFT 194 } snd_mixer_selem_channel_id_t; 195 196 /** Mixer simple element - register options - abstraction level */ 197 enum snd_mixer_selem_regopt_abstract { 198 /** no abstraction - try use all universal controls from driver */ 199 SND_MIXER_SABSTRACT_NONE = 0, 200 /** basic abstraction - Master,PCM,CD,Aux,Record-Gain etc. */ 201 SND_MIXER_SABSTRACT_BASIC, 202 }; 203 204 /** Mixer simple element - register options */ 205 struct snd_mixer_selem_regopt { 206 /** structure version */ 207 int ver; 208 /** v1: abstract layer selection */ 209 enum snd_mixer_selem_regopt_abstract abstract; 210 /** v1: device name (must be NULL when playback_pcm or capture_pcm != NULL) */ 211 const char *device; 212 /** v1: playback PCM connected to mixer device (NULL == none) */ 213 snd_pcm_t *playback_pcm; 214 /** v1: capture PCM connected to mixer device (NULL == none) */ 215 snd_pcm_t *capture_pcm; 216 }; 217 218 /** Mixer simple element identifier */ 219 typedef struct _snd_mixer_selem_id snd_mixer_selem_id_t; 220 221 const char *snd_mixer_selem_channel_name(snd_mixer_selem_channel_id_t channel); 222 223 int snd_mixer_selem_register(snd_mixer_t *mixer, 224 struct snd_mixer_selem_regopt *options, 225 snd_mixer_class_t **classp); 226 void snd_mixer_selem_get_id(snd_mixer_elem_t *element, 227 snd_mixer_selem_id_t *id); 228 const char *snd_mixer_selem_get_name(snd_mixer_elem_t *elem); 229 unsigned int snd_mixer_selem_get_index(snd_mixer_elem_t *elem); 230 snd_mixer_elem_t *snd_mixer_find_selem(snd_mixer_t *mixer, 231 const snd_mixer_selem_id_t *id); 232 233 int snd_mixer_selem_is_active(snd_mixer_elem_t *elem); 234 int snd_mixer_selem_is_playback_mono(snd_mixer_elem_t *elem); 235 int snd_mixer_selem_has_playback_channel(snd_mixer_elem_t *obj, snd_mixer_selem_channel_id_t channel); 236 int snd_mixer_selem_is_capture_mono(snd_mixer_elem_t *elem); 237 int snd_mixer_selem_has_capture_channel(snd_mixer_elem_t *obj, snd_mixer_selem_channel_id_t channel); 238 int snd_mixer_selem_get_capture_group(snd_mixer_elem_t *elem); 239 int snd_mixer_selem_has_common_volume(snd_mixer_elem_t *elem); 240 int snd_mixer_selem_has_playback_volume(snd_mixer_elem_t *elem); 241 int snd_mixer_selem_has_playback_volume_joined(snd_mixer_elem_t *elem); 242 int snd_mixer_selem_has_capture_volume(snd_mixer_elem_t *elem); 243 int snd_mixer_selem_has_capture_volume_joined(snd_mixer_elem_t *elem); 244 int snd_mixer_selem_has_common_switch(snd_mixer_elem_t *elem); 245 int snd_mixer_selem_has_playback_switch(snd_mixer_elem_t *elem); 246 int snd_mixer_selem_has_playback_switch_joined(snd_mixer_elem_t *elem); 247 int snd_mixer_selem_has_capture_switch(snd_mixer_elem_t *elem); 248 int snd_mixer_selem_has_capture_switch_joined(snd_mixer_elem_t *elem); 249 int snd_mixer_selem_has_capture_switch_exclusive(snd_mixer_elem_t *elem); 250 251 int snd_mixer_selem_ask_playback_vol_dB(snd_mixer_elem_t *elem, long value, long *dBvalue); 252 int snd_mixer_selem_ask_capture_vol_dB(snd_mixer_elem_t *elem, long value, long *dBvalue); 253 int snd_mixer_selem_ask_playback_dB_vol(snd_mixer_elem_t *elem, long dBvalue, int dir, long *value); 254 int snd_mixer_selem_ask_capture_dB_vol(snd_mixer_elem_t *elem, long dBvalue, int dir, long *value); 255 int snd_mixer_selem_get_playback_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value); 256 int snd_mixer_selem_get_capture_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value); 257 int snd_mixer_selem_get_playback_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value); 258 int snd_mixer_selem_get_capture_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value); 259 int snd_mixer_selem_get_playback_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int *value); 260 int snd_mixer_selem_get_capture_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int *value); 261 int snd_mixer_selem_set_playback_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value); 262 int snd_mixer_selem_set_capture_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value); 263 int snd_mixer_selem_set_playback_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value, int dir); 264 int snd_mixer_selem_set_capture_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value, int dir); 265 int snd_mixer_selem_set_playback_volume_all(snd_mixer_elem_t *elem, long value); 266 int snd_mixer_selem_set_capture_volume_all(snd_mixer_elem_t *elem, long value); 267 int snd_mixer_selem_set_playback_dB_all(snd_mixer_elem_t *elem, long value, int dir); 268 int snd_mixer_selem_set_capture_dB_all(snd_mixer_elem_t *elem, long value, int dir); 269 int snd_mixer_selem_set_playback_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int value); 270 int snd_mixer_selem_set_capture_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int value); 271 int snd_mixer_selem_set_playback_switch_all(snd_mixer_elem_t *elem, int value); 272 int snd_mixer_selem_set_capture_switch_all(snd_mixer_elem_t *elem, int value); 273 int snd_mixer_selem_get_playback_volume_range(snd_mixer_elem_t *elem, 274 long *min, long *max); 275 int snd_mixer_selem_get_playback_dB_range(snd_mixer_elem_t *elem, 276 long *min, long *max); 277 int snd_mixer_selem_set_playback_volume_range(snd_mixer_elem_t *elem, 278 long min, long max); 279 int snd_mixer_selem_get_capture_volume_range(snd_mixer_elem_t *elem, 280 long *min, long *max); 281 int snd_mixer_selem_get_capture_dB_range(snd_mixer_elem_t *elem, 282 long *min, long *max); 283 int snd_mixer_selem_set_capture_volume_range(snd_mixer_elem_t *elem, 284 long min, long max); 285 286 int snd_mixer_selem_is_enumerated(snd_mixer_elem_t *elem); 287 int snd_mixer_selem_is_enum_playback(snd_mixer_elem_t *elem); 288 int snd_mixer_selem_is_enum_capture(snd_mixer_elem_t *elem); 289 int snd_mixer_selem_get_enum_items(snd_mixer_elem_t *elem); 290 int snd_mixer_selem_get_enum_item_name(snd_mixer_elem_t *elem, unsigned int idx, size_t maxlen, char *str); 291 int snd_mixer_selem_get_enum_item(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, unsigned int *idxp); 292 int snd_mixer_selem_set_enum_item(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, unsigned int idx); 293 294 size_t snd_mixer_selem_id_sizeof(void); 295 /** \hideinitializer 296 * \brief allocate an invalid #snd_mixer_selem_id_t using standard alloca 297 * \param ptr returned pointer 298 */ 299 #define snd_mixer_selem_id_alloca(ptr) __snd_alloca(ptr, snd_mixer_selem_id) 300 int snd_mixer_selem_id_malloc(snd_mixer_selem_id_t **ptr); 301 void snd_mixer_selem_id_free(snd_mixer_selem_id_t *obj); 302 void snd_mixer_selem_id_copy(snd_mixer_selem_id_t *dst, const snd_mixer_selem_id_t *src); 303 const char *snd_mixer_selem_id_get_name(const snd_mixer_selem_id_t *obj); 304 unsigned int snd_mixer_selem_id_get_index(const snd_mixer_selem_id_t *obj); 305 void snd_mixer_selem_id_set_name(snd_mixer_selem_id_t *obj, const char *val); 306 void snd_mixer_selem_id_set_index(snd_mixer_selem_id_t *obj, unsigned int val); 307 int snd_mixer_selem_id_parse(snd_mixer_selem_id_t *dst, const char *str); 308 309 /** \} */ 310 311 /** \} */ 312 313 #ifdef __cplusplus 314 } 315 #endif 316 317 #endif /* __ALSA_MIXER_H */ 318 319