Home | History | Annotate | Download | only in alsa
      1 /**
      2  * \file include/mixer.h
      3  * \brief Application interface library for the ALSA driver
      4  * \author Jaroslav Kysela <perex (at) perex.cz>
      5  * \author Abramo Bagnara <abramo (at) alsa-project.org>
      6  * \author Takashi Iwai <tiwai (at) 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 (legacy) 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_add_elem(snd_mixer_t *mixer, snd_mixer_elem_t *elem);
    128 int snd_mixer_remove_elem(snd_mixer_t *mixer, snd_mixer_elem_t *elem);
    129 int snd_mixer_elem_new(snd_mixer_elem_t **elem,
    130 		       snd_mixer_elem_type_t type,
    131 		       int compare_weight,
    132 		       void *private_data,
    133 		       void (*private_free)(snd_mixer_elem_t *elem));
    134 int snd_mixer_elem_add(snd_mixer_elem_t *elem, snd_mixer_class_t *class_);
    135 int snd_mixer_elem_remove(snd_mixer_elem_t *elem);
    136 void snd_mixer_elem_free(snd_mixer_elem_t *elem);
    137 int snd_mixer_elem_info(snd_mixer_elem_t *elem);
    138 int snd_mixer_elem_value(snd_mixer_elem_t *elem);
    139 int snd_mixer_elem_attach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem);
    140 int snd_mixer_elem_detach(snd_mixer_elem_t *melem, snd_hctl_elem_t *helem);
    141 int snd_mixer_elem_empty(snd_mixer_elem_t *melem);
    142 void *snd_mixer_elem_get_private(const snd_mixer_elem_t *melem);
    143 
    144 size_t snd_mixer_class_sizeof(void);
    145 /** \hideinitializer
    146  * \brief allocate an invalid #snd_mixer_class_t using standard alloca
    147  * \param ptr returned pointer
    148  */
    149 #define snd_mixer_class_alloca(ptr) do { assert(ptr); *ptr = (snd_mixer_class_t *) alloca(snd_mixer_class_sizeof()); memset(*ptr, 0, snd_mixer_class_sizeof()); } while (0)
    150 int snd_mixer_class_malloc(snd_mixer_class_t **ptr);
    151 void snd_mixer_class_free(snd_mixer_class_t *obj);
    152 void snd_mixer_class_copy(snd_mixer_class_t *dst, const snd_mixer_class_t *src);
    153 snd_mixer_t *snd_mixer_class_get_mixer(const snd_mixer_class_t *class_);
    154 snd_mixer_event_t snd_mixer_class_get_event(const snd_mixer_class_t *class_);
    155 void *snd_mixer_class_get_private(const snd_mixer_class_t *class_);
    156 snd_mixer_compare_t snd_mixer_class_get_compare(const snd_mixer_class_t *class_);
    157 int snd_mixer_class_set_event(snd_mixer_class_t *class_, snd_mixer_event_t event);
    158 int snd_mixer_class_set_private(snd_mixer_class_t *class_, void *private_data);
    159 int snd_mixer_class_set_private_free(snd_mixer_class_t *class_, void (*private_free)(snd_mixer_class_t *class_));
    160 int snd_mixer_class_set_compare(snd_mixer_class_t *class_, snd_mixer_compare_t compare);
    161 
    162 /**
    163  *  \defgroup SimpleMixer Simple Mixer Interface
    164  *  \ingroup Mixer
    165  *  The simple mixer interface.
    166  *  \{
    167  */
    168 
    169 /* Simple (legacy) mixer elements API */
    170 
    171 /** Mixer simple element channel identifier */
    172 typedef enum _snd_mixer_selem_channel_id {
    173 	/** Unknown */
    174 	SND_MIXER_SCHN_UNKNOWN = -1,
    175 	/** Front left */
    176 	SND_MIXER_SCHN_FRONT_LEFT = 0,
    177 	/** Front right */
    178 	SND_MIXER_SCHN_FRONT_RIGHT,
    179 	/** Rear left */
    180 	SND_MIXER_SCHN_REAR_LEFT,
    181 	/** Rear right */
    182 	SND_MIXER_SCHN_REAR_RIGHT,
    183 	/** Front center */
    184 	SND_MIXER_SCHN_FRONT_CENTER,
    185 	/** Woofer */
    186 	SND_MIXER_SCHN_WOOFER,
    187 	/** Side Left */
    188 	SND_MIXER_SCHN_SIDE_LEFT,
    189 	/** Side Right */
    190 	SND_MIXER_SCHN_SIDE_RIGHT,
    191 	/** Rear Center */
    192 	SND_MIXER_SCHN_REAR_CENTER,
    193 	SND_MIXER_SCHN_LAST = 31,
    194 	/** Mono (Front left alias) */
    195 	SND_MIXER_SCHN_MONO = SND_MIXER_SCHN_FRONT_LEFT
    196 } snd_mixer_selem_channel_id_t;
    197 
    198 /** Mixer simple element - register options - abstraction level */
    199 enum snd_mixer_selem_regopt_abstract {
    200 	/** no abstraction - try use all universal controls from driver */
    201 	SND_MIXER_SABSTRACT_NONE = 0,
    202 	/** basic abstraction - Master,PCM,CD,Aux,Record-Gain etc. */
    203 	SND_MIXER_SABSTRACT_BASIC,
    204 };
    205 
    206 /** Mixer simple element - register options */
    207 struct snd_mixer_selem_regopt {
    208 	/** structure version */
    209 	int ver;
    210 	/** v1: abstract layer selection */
    211 	enum snd_mixer_selem_regopt_abstract abstract;
    212 	/** v1: device name (must be NULL when playback_pcm or capture_pcm != NULL) */
    213 	const char *device;
    214 	/** v1: playback PCM connected to mixer device (NULL == none) */
    215 	snd_pcm_t *playback_pcm;
    216 	/** v1: capture PCM connected to mixer device (NULL == none) */
    217 	snd_pcm_t *capture_pcm;
    218 };
    219 
    220 /** Mixer simple element identifier */
    221 typedef struct _snd_mixer_selem_id snd_mixer_selem_id_t;
    222 
    223 const char *snd_mixer_selem_channel_name(snd_mixer_selem_channel_id_t channel);
    224 
    225 int snd_mixer_selem_register(snd_mixer_t *mixer,
    226 			     struct snd_mixer_selem_regopt *options,
    227 			     snd_mixer_class_t **classp);
    228 void snd_mixer_selem_get_id(snd_mixer_elem_t *element,
    229 			    snd_mixer_selem_id_t *id);
    230 const char *snd_mixer_selem_get_name(snd_mixer_elem_t *elem);
    231 unsigned int snd_mixer_selem_get_index(snd_mixer_elem_t *elem);
    232 snd_mixer_elem_t *snd_mixer_find_selem(snd_mixer_t *mixer,
    233 				       const snd_mixer_selem_id_t *id);
    234 
    235 int snd_mixer_selem_is_active(snd_mixer_elem_t *elem);
    236 int snd_mixer_selem_is_playback_mono(snd_mixer_elem_t *elem);
    237 int snd_mixer_selem_has_playback_channel(snd_mixer_elem_t *obj, snd_mixer_selem_channel_id_t channel);
    238 int snd_mixer_selem_is_capture_mono(snd_mixer_elem_t *elem);
    239 int snd_mixer_selem_has_capture_channel(snd_mixer_elem_t *obj, snd_mixer_selem_channel_id_t channel);
    240 int snd_mixer_selem_get_capture_group(snd_mixer_elem_t *elem);
    241 int snd_mixer_selem_has_common_volume(snd_mixer_elem_t *elem);
    242 int snd_mixer_selem_has_playback_volume(snd_mixer_elem_t *elem);
    243 int snd_mixer_selem_has_playback_volume_joined(snd_mixer_elem_t *elem);
    244 int snd_mixer_selem_has_capture_volume(snd_mixer_elem_t *elem);
    245 int snd_mixer_selem_has_capture_volume_joined(snd_mixer_elem_t *elem);
    246 int snd_mixer_selem_has_common_switch(snd_mixer_elem_t *elem);
    247 int snd_mixer_selem_has_playback_switch(snd_mixer_elem_t *elem);
    248 int snd_mixer_selem_has_playback_switch_joined(snd_mixer_elem_t *elem);
    249 int snd_mixer_selem_has_capture_switch(snd_mixer_elem_t *elem);
    250 int snd_mixer_selem_has_capture_switch_joined(snd_mixer_elem_t *elem);
    251 int snd_mixer_selem_has_capture_switch_exclusive(snd_mixer_elem_t *elem);
    252 
    253 int snd_mixer_selem_get_playback_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value);
    254 int snd_mixer_selem_get_capture_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value);
    255 int snd_mixer_selem_get_playback_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value);
    256 int snd_mixer_selem_get_capture_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long *value);
    257 int snd_mixer_selem_get_playback_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int *value);
    258 int snd_mixer_selem_get_capture_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int *value);
    259 int snd_mixer_selem_set_playback_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value);
    260 int snd_mixer_selem_set_capture_volume(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value);
    261 int snd_mixer_selem_set_playback_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value, int dir);
    262 int snd_mixer_selem_set_capture_dB(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, long value, int dir);
    263 int snd_mixer_selem_set_playback_volume_all(snd_mixer_elem_t *elem, long value);
    264 int snd_mixer_selem_set_capture_volume_all(snd_mixer_elem_t *elem, long value);
    265 int snd_mixer_selem_set_playback_dB_all(snd_mixer_elem_t *elem, long value, int dir);
    266 int snd_mixer_selem_set_capture_dB_all(snd_mixer_elem_t *elem, long value, int dir);
    267 int snd_mixer_selem_set_playback_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int value);
    268 int snd_mixer_selem_set_capture_switch(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, int value);
    269 int snd_mixer_selem_set_playback_switch_all(snd_mixer_elem_t *elem, int value);
    270 int snd_mixer_selem_set_capture_switch_all(snd_mixer_elem_t *elem, int value);
    271 int snd_mixer_selem_get_playback_volume_range(snd_mixer_elem_t *elem,
    272 					      long *min, long *max);
    273 int snd_mixer_selem_get_playback_dB_range(snd_mixer_elem_t *elem,
    274 					  long *min, long *max);
    275 int snd_mixer_selem_set_playback_volume_range(snd_mixer_elem_t *elem,
    276 					      long min, long max);
    277 int snd_mixer_selem_get_capture_volume_range(snd_mixer_elem_t *elem,
    278 					     long *min, long *max);
    279 int snd_mixer_selem_get_capture_dB_range(snd_mixer_elem_t *elem,
    280 					 long *min, long *max);
    281 int snd_mixer_selem_set_capture_volume_range(snd_mixer_elem_t *elem,
    282 					     long min, long max);
    283 
    284 int snd_mixer_selem_is_enumerated(snd_mixer_elem_t *elem);
    285 int snd_mixer_selem_is_enum_playback(snd_mixer_elem_t *elem);
    286 int snd_mixer_selem_is_enum_capture(snd_mixer_elem_t *elem);
    287 int snd_mixer_selem_get_enum_items(snd_mixer_elem_t *elem);
    288 int snd_mixer_selem_get_enum_item_name(snd_mixer_elem_t *elem, unsigned int idx, size_t maxlen, char *str);
    289 int snd_mixer_selem_get_enum_item(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, unsigned int *idxp);
    290 int snd_mixer_selem_set_enum_item(snd_mixer_elem_t *elem, snd_mixer_selem_channel_id_t channel, unsigned int idx);
    291 
    292 size_t snd_mixer_selem_id_sizeof(void);
    293 /** \hideinitializer
    294  * \brief allocate an invalid #snd_mixer_selem_id_t using standard alloca
    295  * \param ptr returned pointer
    296  */
    297 #define snd_mixer_selem_id_alloca(ptr) do { assert(ptr); *ptr = (snd_mixer_selem_id_t *) alloca(snd_mixer_selem_id_sizeof()); memset(*ptr, 0, snd_mixer_selem_id_sizeof()); } while (0)
    298 int snd_mixer_selem_id_malloc(snd_mixer_selem_id_t **ptr);
    299 void snd_mixer_selem_id_free(snd_mixer_selem_id_t *obj);
    300 void snd_mixer_selem_id_copy(snd_mixer_selem_id_t *dst, const snd_mixer_selem_id_t *src);
    301 const char *snd_mixer_selem_id_get_name(const snd_mixer_selem_id_t *obj);
    302 unsigned int snd_mixer_selem_id_get_index(const snd_mixer_selem_id_t *obj);
    303 void snd_mixer_selem_id_set_name(snd_mixer_selem_id_t *obj, const char *val);
    304 void snd_mixer_selem_id_set_index(snd_mixer_selem_id_t *obj, unsigned int val);
    305 
    306 /** \} */
    307 
    308 /** \} */
    309 
    310 #ifdef __cplusplus
    311 }
    312 #endif
    313 
    314 #endif /* __ALSA_MIXER_H */
    315 
    316