1 /** 2 * \file include/control_external.h 3 * \brief External control plugin SDK 4 * \author Takashi Iwai <tiwai@suse.de> 5 * \date 2005 6 * 7 * External control plugin SDK. 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 */ 26 #ifndef __ALSA_CONTROL_EXTERNAL_H 27 #define __ALSA_CONTROL_EXTERNAL_H 28 29 #include "control.h" 30 31 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 /** 36 * \defgroup CtlPlugin_SDK External Control Plugin SDK 37 * \{ 38 */ 39 40 /** 41 * Define the object entry for external control plugins 42 */ 43 #define SND_CTL_PLUGIN_ENTRY(name) _snd_ctl_##name##_open 44 45 /** 46 * Define the symbols of the given control plugin with versions 47 */ 48 #define SND_CTL_PLUGIN_SYMBOL(name) SND_DLSYM_BUILD_VERSION(SND_CTL_PLUGIN_ENTRY(name), SND_CONTROL_DLSYM_VERSION); 49 50 /** 51 * Define the control plugin 52 */ 53 #define SND_CTL_PLUGIN_DEFINE_FUNC(plugin) \ 54 int SND_CTL_PLUGIN_ENTRY(plugin) (snd_ctl_t **handlep, const char *name,\ 55 snd_config_t *root, snd_config_t *conf, int mode) 56 57 /** External control plugin handle */ 58 typedef struct snd_ctl_ext snd_ctl_ext_t; 59 /** Callback table of control ext */ 60 typedef struct snd_ctl_ext_callback snd_ctl_ext_callback_t; 61 /** Key to access a control pointer */ 62 typedef unsigned long snd_ctl_ext_key_t; 63 64 /* 65 * Protocol version 66 */ 67 #define SND_CTL_EXT_VERSION_MAJOR 1 /**< Protocol major version */ 68 #define SND_CTL_EXT_VERSION_MINOR 0 /**< Protocol minor version */ 69 #define SND_CTL_EXT_VERSION_TINY 0 /**< Protocol tiny version */ 70 /** 71 * external plugin protocol version 72 */ 73 #define SND_CTL_EXT_VERSION ((SND_CTL_EXT_VERSION_MAJOR<<16) |\ 74 (SND_CTL_EXT_VERSION_MINOR<<8) |\ 75 (SND_CTL_EXT_VERSION_TINY)) 76 77 /** Handle of control ext */ 78 struct snd_ctl_ext { 79 /** 80 * protocol version; #SND_CTL_EXT_VERSION must be filled here 81 * before calling #snd_ctl_ext_create() 82 */ 83 unsigned int version; 84 /** 85 * Index of this card; must be filled before calling #snd_ctl_ext_create() 86 */ 87 int card_idx; 88 /** 89 * ID string of this card; must be filled before calling #snd_ctl_ext_create() 90 */ 91 char id[16]; 92 /** 93 * Driver name of this card; must be filled before calling #snd_ctl_ext_create() 94 */ 95 char driver[16]; 96 /** 97 * short name of this card; must be filled before calling #snd_ctl_ext_create() 98 */ 99 char name[32]; 100 /** 101 * Long name of this card; must be filled before calling #snd_ctl_ext_create() 102 */ 103 char longname[80]; 104 /** 105 * Mixer name of this card; must be filled before calling #snd_ctl_ext_create() 106 */ 107 char mixername[80]; 108 /** 109 * poll descriptor 110 */ 111 int poll_fd; 112 113 /** 114 * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create() 115 */ 116 const snd_ctl_ext_callback_t *callback; 117 /** 118 * private data, which can be used freely in the driver callbacks 119 */ 120 void *private_data; 121 /** 122 * control handle filled by #snd_ctl_ext_create() 123 */ 124 snd_ctl_t *handle; 125 126 int nonblock; /**< non-block mode; read-only */ 127 int subscribed; /**< events subscribed; read-only */ 128 }; 129 130 /** Callback table of ext */ 131 struct snd_ctl_ext_callback { 132 /** 133 * close the control handle; optional 134 */ 135 void (*close)(snd_ctl_ext_t *ext); 136 /** 137 * return the total number of elements; required 138 */ 139 int (*elem_count)(snd_ctl_ext_t *ext); 140 /** 141 * return the element id of the given offset (array index); required 142 */ 143 int (*elem_list)(snd_ctl_ext_t *ext, unsigned int offset, snd_ctl_elem_id_t *id); 144 /** 145 * convert the element id to a search key; required 146 */ 147 snd_ctl_ext_key_t (*find_elem)(snd_ctl_ext_t *ext, const snd_ctl_elem_id_t *id); 148 /** 149 * the destructor of the key; optional 150 */ 151 void (*free_key)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key); 152 /** 153 * get the attribute of the element; required 154 */ 155 int (*get_attribute)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 156 int *type, unsigned int *acc, unsigned int *count); 157 /** 158 * get the element information of integer type 159 */ 160 int (*get_integer_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 161 long *imin, long *imax, long *istep); 162 /** 163 * get the element information of integer64 type 164 */ 165 int (*get_integer64_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 166 int64_t *imin, int64_t *imax, int64_t *istep); 167 /** 168 * get the element information of enumerated type 169 */ 170 int (*get_enumerated_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 171 /** 172 * get the name of the enumerated item 173 */ 174 int (*get_enumerated_name)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int item, 175 char *name, size_t name_max_len); 176 /** 177 * read the current values of integer type 178 */ 179 int (*read_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value); 180 /** 181 * read the current values of integer64 type 182 */ 183 int (*read_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value); 184 /** 185 * read the current values of enumerated type 186 */ 187 int (*read_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 188 /** 189 * read the current values of bytes type 190 */ 191 int (*read_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data, 192 size_t max_bytes); 193 /** 194 * read the current values of iec958 type 195 */ 196 int (*read_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958); 197 /** 198 * update the current values of integer type with the given values 199 */ 200 int (*write_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value); 201 /** 202 * update the current values of integer64 type with the given values 203 */ 204 int (*write_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value); 205 /** 206 * update the current values of enumerated type with the given values 207 */ 208 int (*write_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 209 /** 210 * update the current values of bytes type with the given values 211 */ 212 int (*write_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data, 213 size_t max_bytes); 214 /** 215 * update the current values of iec958 type with the given values 216 */ 217 int (*write_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958); 218 /** 219 * subscribe/unsubscribe the event notification; optional 220 */ 221 void (*subscribe_events)(snd_ctl_ext_t *ext, int subscribe); 222 /** 223 * read a pending notification event; optional 224 */ 225 int (*read_event)(snd_ctl_ext_t *ext, snd_ctl_elem_id_t *id, unsigned int *event_mask); 226 /** 227 * return the number of poll descriptors; optional 228 */ 229 int (*poll_descriptors_count)(snd_ctl_ext_t *ext); 230 /** 231 * fill the poll descriptors; optional 232 */ 233 int (*poll_descriptors)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int space); 234 /** 235 * mangle the revents of poll descriptors 236 */ 237 int (*poll_revents)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int nfds, unsigned short *revents); 238 }; 239 240 /** 241 * The access type bits stored in get_attribute callback 242 */ 243 typedef enum snd_ctl_ext_access { 244 SND_CTL_EXT_ACCESS_READ = (1<<0), 245 SND_CTL_EXT_ACCESS_WRITE = (1<<1), 246 SND_CTL_EXT_ACCESS_READWRITE = (3<<0), 247 SND_CTL_EXT_ACCESS_VOLATILE = (1<<2), 248 SND_CTL_EXT_ACCESS_INACTIVE = (1<<8), 249 } snd_ctl_ext_access_t; 250 251 /** 252 * find_elem callback returns this if no matching control element is found 253 */ 254 #define SND_CTL_EXT_KEY_NOT_FOUND (snd_ctl_ext_key_t)(-1) 255 256 int snd_ctl_ext_create(snd_ctl_ext_t *ext, const char *name, int mode); 257 int snd_ctl_ext_delete(snd_ctl_ext_t *ext); 258 259 /** \} */ 260 261 #ifdef __cplusplus 262 } 263 #endif 264 265 #endif /* __ALSA_CONTROL_EXTERNAL_H */ 266