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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 #ifdef DOC_HIDDEN 64 /* redefine typedef's for stupid doxygen */ 65 typedef snd_ctl_ext snd_ctl_ext_t; 66 typedef snd_ctl_ext_callback snd_ctl_ext_callback_t; 67 #endif 68 /** Callback to handle TLV commands. */ 69 typedef int (snd_ctl_ext_tlv_rw_t)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int op_flag, unsigned int numid, 70 unsigned int *tlv, unsigned int tlv_size); 71 72 /* 73 * Protocol version 74 */ 75 #define SND_CTL_EXT_VERSION_MAJOR 1 /**< Protocol major version */ 76 #define SND_CTL_EXT_VERSION_MINOR 0 /**< Protocol minor version */ 77 #define SND_CTL_EXT_VERSION_TINY 1 /**< Protocol tiny version */ 78 /** 79 * external plugin protocol version 80 */ 81 #define SND_CTL_EXT_VERSION ((SND_CTL_EXT_VERSION_MAJOR<<16) |\ 82 (SND_CTL_EXT_VERSION_MINOR<<8) |\ 83 (SND_CTL_EXT_VERSION_TINY)) 84 85 /** Handle of control ext */ 86 struct snd_ctl_ext { 87 /** 88 * protocol version; #SND_CTL_EXT_VERSION must be filled here 89 * before calling #snd_ctl_ext_create() 90 */ 91 unsigned int version; 92 /** 93 * Index of this card; must be filled before calling #snd_ctl_ext_create() 94 */ 95 int card_idx; 96 /** 97 * ID string of this card; must be filled before calling #snd_ctl_ext_create() 98 */ 99 char id[16]; 100 /** 101 * Driver name of this card; must be filled before calling #snd_ctl_ext_create() 102 */ 103 char driver[16]; 104 /** 105 * short name of this card; must be filled before calling #snd_ctl_ext_create() 106 */ 107 char name[32]; 108 /** 109 * Long name of this card; must be filled before calling #snd_ctl_ext_create() 110 */ 111 char longname[80]; 112 /** 113 * Mixer name of this card; must be filled before calling #snd_ctl_ext_create() 114 */ 115 char mixername[80]; 116 /** 117 * poll descriptor 118 */ 119 int poll_fd; 120 121 /** 122 * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create() 123 */ 124 const snd_ctl_ext_callback_t *callback; 125 /** 126 * private data, which can be used freely in the driver callbacks 127 */ 128 void *private_data; 129 /** 130 * control handle filled by #snd_ctl_ext_create() 131 */ 132 snd_ctl_t *handle; 133 134 int nonblock; /**< non-block mode; read-only */ 135 int subscribed; /**< events subscribed; read-only */ 136 137 /** 138 * optional TLV data for the control (since protocol 1.0.1) 139 */ 140 union { 141 snd_ctl_ext_tlv_rw_t *c; 142 const unsigned int *p; 143 } tlv; 144 }; 145 146 /** Callback table of ext. */ 147 struct snd_ctl_ext_callback { 148 /** 149 * close the control handle; optional 150 */ 151 void (*close)(snd_ctl_ext_t *ext); 152 /** 153 * return the total number of elements; required 154 */ 155 int (*elem_count)(snd_ctl_ext_t *ext); 156 /** 157 * return the element id of the given offset (array index); required 158 */ 159 int (*elem_list)(snd_ctl_ext_t *ext, unsigned int offset, snd_ctl_elem_id_t *id); 160 /** 161 * convert the element id to a search key; required 162 */ 163 snd_ctl_ext_key_t (*find_elem)(snd_ctl_ext_t *ext, const snd_ctl_elem_id_t *id); 164 /** 165 * the destructor of the key; optional 166 */ 167 void (*free_key)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key); 168 /** 169 * get the attribute of the element; required 170 */ 171 int (*get_attribute)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 172 int *type, unsigned int *acc, unsigned int *count); 173 /** 174 * get the element information of integer type 175 */ 176 int (*get_integer_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 177 long *imin, long *imax, long *istep); 178 /** 179 * get the element information of integer64 type 180 */ 181 int (*get_integer64_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, 182 int64_t *imin, int64_t *imax, int64_t *istep); 183 /** 184 * get the element information of enumerated type 185 */ 186 int (*get_enumerated_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 187 /** 188 * get the name of the enumerated item 189 */ 190 int (*get_enumerated_name)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int item, 191 char *name, size_t name_max_len); 192 /** 193 * read the current values of integer type 194 */ 195 int (*read_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value); 196 /** 197 * read the current values of integer64 type 198 */ 199 int (*read_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value); 200 /** 201 * read the current values of enumerated type 202 */ 203 int (*read_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 204 /** 205 * read the current values of bytes type 206 */ 207 int (*read_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data, 208 size_t max_bytes); 209 /** 210 * read the current values of iec958 type 211 */ 212 int (*read_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958); 213 /** 214 * update the current values of integer type with the given values 215 */ 216 int (*write_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value); 217 /** 218 * update the current values of integer64 type with the given values 219 */ 220 int (*write_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value); 221 /** 222 * update the current values of enumerated type with the given values 223 */ 224 int (*write_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items); 225 /** 226 * update the current values of bytes type with the given values 227 */ 228 int (*write_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data, 229 size_t max_bytes); 230 /** 231 * update the current values of iec958 type with the given values 232 */ 233 int (*write_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958); 234 /** 235 * subscribe/unsubscribe the event notification; optional 236 */ 237 void (*subscribe_events)(snd_ctl_ext_t *ext, int subscribe); 238 /** 239 * read a pending notification event; optional 240 */ 241 int (*read_event)(snd_ctl_ext_t *ext, snd_ctl_elem_id_t *id, unsigned int *event_mask); 242 /** 243 * return the number of poll descriptors; optional 244 */ 245 int (*poll_descriptors_count)(snd_ctl_ext_t *ext); 246 /** 247 * fill the poll descriptors; optional 248 */ 249 int (*poll_descriptors)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int space); 250 /** 251 * mangle the revents of poll descriptors 252 */ 253 int (*poll_revents)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int nfds, unsigned short *revents); 254 }; 255 256 /** 257 * The access type bits stored in get_attribute callback 258 */ 259 typedef enum snd_ctl_ext_access { 260 SND_CTL_EXT_ACCESS_READ = (1<<0), 261 SND_CTL_EXT_ACCESS_WRITE = (1<<1), 262 SND_CTL_EXT_ACCESS_READWRITE = (3<<0), 263 SND_CTL_EXT_ACCESS_VOLATILE = (1<<2), 264 SND_CTL_EXT_ACCESS_TLV_READ = (1<<4), 265 SND_CTL_EXT_ACCESS_TLV_WRITE = (1<<5), 266 SND_CTL_EXT_ACCESS_TLV_READWRITE = (3<<4), 267 SND_CTL_EXT_ACCESS_TLV_COMMAND = (1<<6), 268 SND_CTL_EXT_ACCESS_INACTIVE = (1<<8), 269 SND_CTL_EXT_ACCESS_TLV_CALLBACK = (1<<28), 270 } snd_ctl_ext_access_t; 271 272 /** 273 * find_elem callback returns this if no matching control element is found 274 */ 275 #define SND_CTL_EXT_KEY_NOT_FOUND (snd_ctl_ext_key_t)(-1) 276 277 int snd_ctl_ext_create(snd_ctl_ext_t *ext, const char *name, int mode); 278 int snd_ctl_ext_delete(snd_ctl_ext_t *ext); 279 280 /** \} */ 281 282 #ifdef __cplusplus 283 } 284 #endif 285 286 #endif /* __ALSA_CONTROL_EXTERNAL_H */ 287