include/control_external.h

   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 #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 */