jpayne@69: /**
jpayne@69:  * \file include/control_external.h
jpayne@69:  * \brief External control plugin SDK
jpayne@69:  * \author Takashi Iwai <tiwai@suse.de>
jpayne@69:  * \date 2005
jpayne@69:  *
jpayne@69:  * External control plugin SDK.
jpayne@69:  */
jpayne@69: 
jpayne@69: /*
jpayne@69:  *   This library is free software; you can redistribute it and/or modify
jpayne@69:  *   it under the terms of the GNU Lesser General Public License as
jpayne@69:  *   published by the Free Software Foundation; either version 2.1 of
jpayne@69:  *   the License, or (at your option) any later version.
jpayne@69:  *
jpayne@69:  *   This program is distributed in the hope that it will be useful,
jpayne@69:  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
jpayne@69:  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
jpayne@69:  *   GNU Lesser General Public License for more details.
jpayne@69:  *
jpayne@69:  *   You should have received a copy of the GNU Lesser General Public
jpayne@69:  *   License along with this library; if not, write to the Free Software
jpayne@69:  *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
jpayne@69:  *
jpayne@69:  */
jpayne@69: #ifndef __ALSA_CONTROL_EXTERNAL_H
jpayne@69: #define __ALSA_CONTROL_EXTERNAL_H
jpayne@69: 
jpayne@69: #include "control.h"
jpayne@69: 
jpayne@69: #ifdef __cplusplus
jpayne@69: extern "C" {
jpayne@69: #endif
jpayne@69: 
jpayne@69: /**
jpayne@69:  *  \defgroup CtlPlugin_SDK External Control Plugin SDK
jpayne@69:  *  \{
jpayne@69:  */
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Define the object entry for external control plugins
jpayne@69:  */
jpayne@69: #define SND_CTL_PLUGIN_ENTRY(name) _snd_ctl_##name##_open
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Define the symbols of the given control plugin with versions
jpayne@69:  */
jpayne@69: #define SND_CTL_PLUGIN_SYMBOL(name) SND_DLSYM_BUILD_VERSION(SND_CTL_PLUGIN_ENTRY(name), SND_CONTROL_DLSYM_VERSION);
jpayne@69: 
jpayne@69: /**
jpayne@69:  * Define the control plugin
jpayne@69:  */
jpayne@69: #define SND_CTL_PLUGIN_DEFINE_FUNC(plugin) \
jpayne@69: int SND_CTL_PLUGIN_ENTRY(plugin) (snd_ctl_t **handlep, const char *name,\
jpayne@69: 				  snd_config_t *root, snd_config_t *conf, int mode)
jpayne@69: 
jpayne@69: /** External control plugin handle */
jpayne@69: typedef struct snd_ctl_ext snd_ctl_ext_t;
jpayne@69: /** Callback table of control ext */
jpayne@69: typedef struct snd_ctl_ext_callback snd_ctl_ext_callback_t;
jpayne@69: /** Key to access a control pointer */
jpayne@69: typedef unsigned long snd_ctl_ext_key_t;
jpayne@69: #ifdef DOC_HIDDEN
jpayne@69: /* redefine typedef's for stupid doxygen */
jpayne@69: typedef snd_ctl_ext snd_ctl_ext_t;
jpayne@69: typedef snd_ctl_ext_callback snd_ctl_ext_callback_t;
jpayne@69: #endif
jpayne@69: /** Callback to handle TLV commands. */
jpayne@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,
jpayne@69: 				   unsigned int *tlv, unsigned int tlv_size);
jpayne@69: 
jpayne@69: /*
jpayne@69:  * Protocol version
jpayne@69:  */
jpayne@69: #define SND_CTL_EXT_VERSION_MAJOR	1	/**< Protocol major version */
jpayne@69: #define SND_CTL_EXT_VERSION_MINOR	0	/**< Protocol minor version */
jpayne@69: #define SND_CTL_EXT_VERSION_TINY	1	/**< Protocol tiny version */
jpayne@69: /**
jpayne@69:  * external plugin protocol version
jpayne@69:  */
jpayne@69: #define SND_CTL_EXT_VERSION		((SND_CTL_EXT_VERSION_MAJOR<<16) |\
jpayne@69: 					 (SND_CTL_EXT_VERSION_MINOR<<8) |\
jpayne@69: 					 (SND_CTL_EXT_VERSION_TINY))
jpayne@69: 
jpayne@69: /** Handle of control ext */
jpayne@69: struct snd_ctl_ext {
jpayne@69: 	/**
jpayne@69: 	 * protocol version; #SND_CTL_EXT_VERSION must be filled here
jpayne@69: 	 * before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	unsigned int version;
jpayne@69: 	/**
jpayne@69: 	 * Index of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	int card_idx;
jpayne@69: 	/**
jpayne@69: 	 * ID string of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	char id[16];
jpayne@69: 	/**
jpayne@69: 	 * Driver name of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	char driver[16];
jpayne@69: 	/**
jpayne@69: 	 * short name of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	char name[32];
jpayne@69: 	/**
jpayne@69: 	 * Long name of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	char longname[80];
jpayne@69: 	/**
jpayne@69: 	 * Mixer name of this card; must be filled before calling #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	char mixername[80];
jpayne@69: 	/**
jpayne@69: 	 * poll descriptor
jpayne@69: 	 */
jpayne@69: 	int poll_fd;
jpayne@69: 
jpayne@69: 	/**
jpayne@69: 	 * callbacks of this plugin; must be filled before calling #snd_pcm_ioplug_create()
jpayne@69: 	 */
jpayne@69: 	const snd_ctl_ext_callback_t *callback;
jpayne@69: 	/**
jpayne@69: 	 * private data, which can be used freely in the driver callbacks
jpayne@69: 	 */
jpayne@69: 	void *private_data;
jpayne@69: 	/**
jpayne@69: 	 * control handle filled by #snd_ctl_ext_create()
jpayne@69: 	 */
jpayne@69: 	snd_ctl_t *handle;
jpayne@69: 
jpayne@69: 	int nonblock;			/**< non-block mode; read-only */
jpayne@69: 	int subscribed;			/**< events subscribed; read-only */
jpayne@69: 
jpayne@69: 	/**
jpayne@69: 	 * optional TLV data for the control (since protocol 1.0.1)
jpayne@69: 	 */
jpayne@69: 	union {
jpayne@69: 		snd_ctl_ext_tlv_rw_t *c;
jpayne@69: 		const unsigned int *p;
jpayne@69: 	} tlv;
jpayne@69: };
jpayne@69: 
jpayne@69: /** Callback table of ext. */
jpayne@69: struct snd_ctl_ext_callback {
jpayne@69: 	/**
jpayne@69: 	 * close the control handle; optional
jpayne@69: 	 */
jpayne@69: 	void (*close)(snd_ctl_ext_t *ext);
jpayne@69: 	/**
jpayne@69: 	 * return the total number of elements; required
jpayne@69: 	 */
jpayne@69: 	int (*elem_count)(snd_ctl_ext_t *ext);
jpayne@69: 	/**
jpayne@69: 	 * return the element id of the given offset (array index); required
jpayne@69: 	 */
jpayne@69: 	int (*elem_list)(snd_ctl_ext_t *ext, unsigned int offset, snd_ctl_elem_id_t *id);
jpayne@69: 	/**
jpayne@69: 	 * convert the element id to a search key; required
jpayne@69: 	 */
jpayne@69: 	snd_ctl_ext_key_t (*find_elem)(snd_ctl_ext_t *ext, const snd_ctl_elem_id_t *id);
jpayne@69: 	/**
jpayne@69: 	 * the destructor of the key; optional
jpayne@69: 	 */
jpayne@69: 	void (*free_key)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key);
jpayne@69: 	/**
jpayne@69: 	 * get the attribute of the element; required
jpayne@69: 	 */
jpayne@69: 	int (*get_attribute)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key,
jpayne@69: 			     int *type, unsigned int *acc, unsigned int *count);
jpayne@69: 	/**
jpayne@69: 	 * get the element information of integer type
jpayne@69: 	 */
jpayne@69: 	int (*get_integer_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key,
jpayne@69: 				long *imin, long *imax, long *istep);
jpayne@69: 	/**
jpayne@69: 	 * get the element information of integer64 type
jpayne@69: 	 */
jpayne@69: 	int (*get_integer64_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key,
jpayne@69: 				  int64_t *imin, int64_t *imax, int64_t *istep);
jpayne@69: 	/**
jpayne@69: 	 * get the element information of enumerated type
jpayne@69: 	 */
jpayne@69: 	int (*get_enumerated_info)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items);
jpayne@69: 	/**
jpayne@69: 	 * get the name of the enumerated item
jpayne@69: 	 */
jpayne@69: 	int (*get_enumerated_name)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int item,
jpayne@69: 				   char *name, size_t name_max_len);
jpayne@69: 	/**
jpayne@69: 	 * read the current values of integer type
jpayne@69: 	 */
jpayne@69: 	int (*read_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value);
jpayne@69: 	/**
jpayne@69: 	 * read the current values of integer64 type
jpayne@69: 	 */
jpayne@69: 	int (*read_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value);
jpayne@69: 	/**
jpayne@69: 	 * read the current values of enumerated type
jpayne@69: 	 */
jpayne@69: 	int (*read_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items);
jpayne@69: 	/**
jpayne@69: 	 * read the current values of bytes type
jpayne@69: 	 */
jpayne@69: 	int (*read_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data,
jpayne@69: 			  size_t max_bytes);
jpayne@69: 	/**
jpayne@69: 	 * read the current values of iec958 type
jpayne@69: 	 */
jpayne@69: 	int (*read_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958);
jpayne@69: 	/**
jpayne@69: 	 * update the current values of integer type with the given values
jpayne@69: 	 */
jpayne@69: 	int (*write_integer)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, long *value);
jpayne@69: 	/**
jpayne@69: 	 * update the current values of integer64 type with the given values
jpayne@69: 	 */
jpayne@69: 	int (*write_integer64)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, int64_t *value);
jpayne@69: 	/**
jpayne@69: 	 * update the current values of enumerated type with the given values
jpayne@69: 	 */
jpayne@69: 	int (*write_enumerated)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned int *items);
jpayne@69: 	/**
jpayne@69: 	 * update the current values of bytes type with the given values
jpayne@69: 	 */
jpayne@69: 	int (*write_bytes)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, unsigned char *data,
jpayne@69: 			   size_t max_bytes);
jpayne@69: 	/**
jpayne@69: 	 * update the current values of iec958 type with the given values
jpayne@69: 	 */
jpayne@69: 	int (*write_iec958)(snd_ctl_ext_t *ext, snd_ctl_ext_key_t key, snd_aes_iec958_t *iec958);
jpayne@69: 	/**
jpayne@69: 	 * subscribe/unsubscribe the event notification; optional
jpayne@69: 	 */
jpayne@69: 	void (*subscribe_events)(snd_ctl_ext_t *ext, int subscribe);
jpayne@69: 	/**
jpayne@69: 	 * read a pending notification event; optional
jpayne@69: 	 */
jpayne@69: 	int (*read_event)(snd_ctl_ext_t *ext, snd_ctl_elem_id_t *id, unsigned int *event_mask);
jpayne@69: 	/**
jpayne@69: 	 * return the number of poll descriptors; optional
jpayne@69: 	 */
jpayne@69: 	int (*poll_descriptors_count)(snd_ctl_ext_t *ext);
jpayne@69: 	/**
jpayne@69: 	 * fill the poll descriptors; optional
jpayne@69: 	 */
jpayne@69: 	int (*poll_descriptors)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int space);
jpayne@69: 	/**
jpayne@69: 	 * mangle the revents of poll descriptors
jpayne@69: 	 */
jpayne@69: 	int (*poll_revents)(snd_ctl_ext_t *ext, struct pollfd *pfds, unsigned int nfds, unsigned short *revents);
jpayne@69: };
jpayne@69: 
jpayne@69: /**
jpayne@69:  * The access type bits stored in get_attribute callback
jpayne@69:  */
jpayne@69: typedef enum snd_ctl_ext_access {
jpayne@69: 	SND_CTL_EXT_ACCESS_READ = (1<<0),
jpayne@69: 	SND_CTL_EXT_ACCESS_WRITE = (1<<1),
jpayne@69: 	SND_CTL_EXT_ACCESS_READWRITE = (3<<0),
jpayne@69: 	SND_CTL_EXT_ACCESS_VOLATILE = (1<<2),
jpayne@69: 	SND_CTL_EXT_ACCESS_TLV_READ = (1<<4),
jpayne@69: 	SND_CTL_EXT_ACCESS_TLV_WRITE = (1<<5),
jpayne@69: 	SND_CTL_EXT_ACCESS_TLV_READWRITE = (3<<4),
jpayne@69: 	SND_CTL_EXT_ACCESS_TLV_COMMAND = (1<<6),
jpayne@69: 	SND_CTL_EXT_ACCESS_INACTIVE = (1<<8),
jpayne@69: 	SND_CTL_EXT_ACCESS_TLV_CALLBACK = (1<<28),
jpayne@69: } snd_ctl_ext_access_t;
jpayne@69: 
jpayne@69: /**
jpayne@69:  * find_elem callback returns this if no matching control element is found
jpayne@69:  */
jpayne@69: #define SND_CTL_EXT_KEY_NOT_FOUND	(snd_ctl_ext_key_t)(-1)
jpayne@69: 
jpayne@69: int snd_ctl_ext_create(snd_ctl_ext_t *ext, const char *name, int mode);
jpayne@69: int snd_ctl_ext_delete(snd_ctl_ext_t *ext);
jpayne@69: 
jpayne@69: /** \} */
jpayne@69: 
jpayne@69: #ifdef __cplusplus
jpayne@69: }
jpayne@69: #endif
jpayne@69: 
jpayne@69: #endif /* __ALSA_CONTROL_EXTERNAL_H */