include/mixer.h

   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., 59 Temple Place, Suite 330, Boston, MA  02111-1307 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
 308 /** \} */
 309
 310 /** \} */
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif /* __ALSA_MIXER_H */
 317