/**

 * \file control/control.c

 * \brief CTL interface - primitive controls

 * \author Abramo Bagnara <abramo@alsa-project.org>

 * \date 2000

 *

 * CTL interface is designed to access primitive controls.

 * See \ref control page for more details.

 */

/*

 *  Control Interface - main file

 *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>

 *

 *

 *   This library is free software; you can redistribute it and/or modify

 *   it under the terms of the GNU Lesser General Public License as

 *   published by the Free Software Foundation; either version 2.1 of

 *   the License, or (at your option) any later version.

 *

 *   This program is distributed in the hope that it will be useful,

 *   but WITHOUT ANY WARRANTY; without even the implied warranty of

 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 *   GNU Lesser General Public License for more details.

 *

 *   You should have received a copy of the GNU Lesser General Public

 *   License along with this library; if not, write to the Free Software

 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA

 *

 */

/*! \page control Control interface

Control interface is designed to access primitive controls. There is

also interface notifying about control and structure changes.

\section control_general_overview General overview

In ALSA control feature, each sound card can have control elements. The elements

are managed according to below model.

 - element set

   - A set of elements with the same attribute (i.e. name, get/put operations).

     Some element sets can be added to a sound card by drivers in kernel and

     userspace applications.

 - element

   - An element can be identified by userspace applications. Each element has

     own identical information.

 - member

   - An element includes some members to have a value. The value of each member

     can be changed by both of userspace applications and drivers in kernel.

Each element can be identified by two ways; a combination of name and index, or

numerical number (numid).

The type of element set is one of integer, integerr64, boolean, enumerators,

bytes and IEC958 structure. This indicates the type of value for each member in

elements included in the element set.

When the value of member is changed, corresponding events are transferred to

userspace applications. The applications should subscribe any events in advance.

\section tlv_blob Supplemental data for elements in an element set

TLV feature is designed to transfer data in a shape of Type/Length/Value,

between a driver and any userspace applications. The main purpose is to attach

supplement information for elements to an element set; e.g. dB range.

At first, this feature was implemented to add pre-defined data readable to

userspace applications. Soon, it was extended to handle several operations;

read, write and command. The original implementation remains as the read

operation. The command operation allows drivers to have own implementations

against requests from userspace applications.

This feature was introduced to ALSA control feature in 2006, at commit

c7a0708a2362, corresponding to a series of work for Linux kernel (42750b04c5ba

and 8aa9b586e420).

There's no limitation about maximum size of the data, therefore it can be used

to deliver quite large arbitrary data from userspace to in-kernel drivers via

ALSA control character device. Focusing on this nature, as of 2016, some

in-kernel implementations utilize this feature for I/O operations. This is

against the original design.

*/

#include <stdio.h>

#include <stdlib.h>

#include <stdint.h>

#include <stdarg.h>

#include <unistd.h>

#include <string.h>

#include <fcntl.h>

#include <signal.h>

#include <poll.h>

#include <stdbool.h>

#include "control_local.h"

/**

 * \brief get identifier of CTL handle

 * \param ctl CTL handle

 * \return ascii identifier of CTL handle

 *

 * Returns the ASCII identifier of given CTL handle. It's the same

 * identifier specified in snd_ctl_open().

 */

const char *snd_ctl_name(snd_ctl_t *ctl)

{

	assert(ctl);

	return ctl->name;

}

/**

 * \brief get type of CTL handle

 * \param ctl CTL handle

 * \return type of CTL handle

 *

 * Returns the type #snd_ctl_type_t of given CTL handle.

 */

snd_ctl_type_t snd_ctl_type(snd_ctl_t *ctl)

{

	assert(ctl);

	return ctl->type;

}

/**

 * \brief close CTL handle

 * \param ctl CTL handle

 * \return 0 on success otherwise a negative error code

 *

 * Closes the specified CTL handle and frees all associated

 * resources.

 */

int snd_ctl_close(snd_ctl_t *ctl)

{

	int err;

	while (!list_empty(&ctl->async_handlers)) {

		snd_async_handler_t *h = list_entry(&ctl->async_handlers.next, snd_async_handler_t, hlist);

		snd_async_del_handler(h);

	}

	err = ctl->ops->close(ctl);

	free(ctl->name);

	snd_dlobj_cache_put(ctl->open_func);

	free(ctl);

	return err;

}

/**

 * \brief set nonblock mode

 * \param ctl CTL handle

 * \param nonblock 0 = block, 1 = nonblock mode, 2 = abort

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_nonblock(snd_ctl_t *ctl, int nonblock)

{

	int err;

	assert(ctl);

	err = ctl->ops->nonblock(ctl, nonblock);

	if (err < 0)

		return err;

	ctl->nonblock = nonblock;

	return 0;

}

#ifndef DOC_HIDDEN

int snd_ctl_new(snd_ctl_t **ctlp, snd_ctl_type_t type, const char *name)

{

	snd_ctl_t *ctl;

	ctl = calloc(1, sizeof(*ctl));

	if (!ctl)

		return -ENOMEM;

	ctl->type = type;

	if (name)

		ctl->name = strdup(name);

	INIT_LIST_HEAD(&ctl->async_handlers);

	*ctlp = ctl;

	return 0;

}

/**

 * \brief set async mode

 * \param ctl CTL handle

 * \param sig Signal to raise: < 0 disable, 0 default (SIGIO)

 * \param pid Process ID to signal: 0 current

 * \return 0 on success otherwise a negative error code

 *

 * A signal is raised when a change happens.

 */

int snd_ctl_async(snd_ctl_t *ctl, int sig, pid_t pid)

{

	assert(ctl);

	if (sig == 0)

		sig = SIGIO;

	if (pid == 0)

		pid = getpid();

	return ctl->ops->async(ctl, sig, pid);

}

#endif

/**

 * \brief get count of poll descriptors for CTL handle

 * \param ctl CTL handle

 * \return count of poll descriptors

 */

int snd_ctl_poll_descriptors_count(snd_ctl_t *ctl)

{

	assert(ctl);

	if (ctl->ops->poll_descriptors_count)

		return ctl->ops->poll_descriptors_count(ctl);

	if (ctl->poll_fd < 0)

		return 0;

	return 1;

}

/**

 * \brief get poll descriptors

 * \param ctl CTL handle

 * \param pfds array of poll descriptors

 * \param space space in the poll descriptor array

 * \return count of filled descriptors

 */

int snd_ctl_poll_descriptors(snd_ctl_t *ctl, struct pollfd *pfds, unsigned int space)

{

	assert(ctl && pfds);

	if (ctl->ops->poll_descriptors)

		return ctl->ops->poll_descriptors(ctl, pfds, space);

	if (ctl->poll_fd < 0)

		return 0;

	if (space > 0) {

		pfds->fd = ctl->poll_fd;

		pfds->events = POLLIN|POLLERR|POLLNVAL;

		return 1;

	}

	return 0;

}

/**

 * \brief get returned events from poll descriptors

 * \param ctl CTL handle

 * \param pfds array of poll descriptors

 * \param nfds count of poll descriptors

 * \param revents returned events

 * \return zero if success, otherwise a negative error code

 */

int snd_ctl_poll_descriptors_revents(snd_ctl_t *ctl, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)

{

	assert(ctl && pfds && revents);

	if (ctl->ops->poll_revents)

		return ctl->ops->poll_revents(ctl, pfds, nfds, revents);

	if (nfds == 1) {

		*revents = pfds->revents;

                return 0;

	}

	return -EINVAL;

}

/**

 * \brief Ask to be informed about events (poll, #snd_async_add_ctl_handler, #snd_ctl_read)

 * \param ctl CTL handle

 * \param subscribe 0 = unsubscribe, 1 = subscribe, -1 = check subscribe or not

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_subscribe_events(snd_ctl_t *ctl, int subscribe)

{

	assert(ctl);

	return ctl->ops->subscribe_events(ctl, subscribe);

}

/**

 * \brief Get card related information

 * \param ctl CTL handle

 * \param info Card info pointer

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_card_info(snd_ctl_t *ctl, snd_ctl_card_info_t *info)

{

	assert(ctl && info);

	return ctl->ops->card_info(ctl, info);

}

/**

 * \brief Get a list of element identifiers

 * \param ctl CTL handle

 * \param list CTL element identifiers list pointer

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_elem_list(snd_ctl_t *ctl, snd_ctl_elem_list_t *list)

{

	assert(ctl && list);

	assert(list->space == 0 || list->pids);

	return ctl->ops->element_list(ctl, list);

}

/**

 * \brief Get CTL element information

 * \param ctl CTL handle

 * \param info CTL element id/information pointer

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_elem_info(snd_ctl_t *ctl, snd_ctl_elem_info_t *info)

{

	assert(ctl && info && (info->id.name[0] || info->id.numid));

	return ctl->ops->element_info(ctl, info);

}

#if 0 /* deprecated */

static bool validate_element_member_dimension(snd_ctl_elem_info_t *info)

{

	unsigned int members;

	unsigned int i;

	if (info->dimen.d[0] == 0)

		return true;

	members = 1;

	for (i = 0; i < ARRAY_SIZE(info->dimen.d); ++i) {

		if (info->dimen.d[i] == 0)

			break;

		members *= info->dimen.d[i];

		if (members > info->count)

			return false;

	}

	for (++i; i < ARRAY_SIZE(info->dimen.d); ++i) {

		if (info->dimen.d[i] > 0)

			return false;

	}

	return members == info->count;

}

#else /* deprecated */

#define validate_element_member_dimension(info)		true

#endif /* deprecated */

/**

 * \brief Create and add some user-defined control elements of integer type.

 * \param ctl A handle of backend module for control interface.

 * \param info Common iformation for a new element set, with ID of the first new

 *	       element.

 * \param element_count The number of elements added by this operation.

 * \param member_count The number of members which a element has to

 *			   represent its states.

 * \param min Minimum value for each member of the elements.

 * \param max Maximum value for each member of the elements.

 * \param step The step of value for each member in the elements.

 * \return Zero on success, otherwise a negative error code.

 *

 * This function creates some user elements with integer type. These elements

 * are not controlled by device drivers in kernel. They can be operated by the

 * same way as usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify new control

 * elements. After returning, all fields of \a id are filled. A element can be

 * identified by the combination of name and index, or by numid.

 *

 * All of members in the new elements are locked. The value of each member is

 * initialized with the minimum value.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A element with ID \a id already exists.

 * 
-EINVAL

 * 
Some arguments include invalid value; i.e. ID field in \a info has no

 *     name, or the number of members is not between 1 to 127.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user elements.

 * 
-ENXIO

 * 
This backend module does not support user elements of integer type.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 *

 * \par Compatibility:

 * This function is added in version 1.1.2.

 */

int snd_ctl_add_integer_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,

				 unsigned int element_count,

				 unsigned int member_count,

				 long min, long max, long step)

{

	snd_ctl_elem_value_t data = {0};

	unsigned int i;

	unsigned int j;

	unsigned int numid;

	int err;

	if (ctl == NULL || info == NULL || info->id.name[0] == '\0')

		return -EINVAL;

	info->type = SND_CTL_ELEM_TYPE_INTEGER;

	info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_USER;

	info->owner = element_count;

	info->count = member_count;

	info->value.integer.min = min;

	info->value.integer.max = max;

	info->value.integer.step = step;

	if (!validate_element_member_dimension(info))

		return -EINVAL;

	err = ctl->ops->element_add(ctl, info);

	if (err < 0)

		return err;

	numid = snd_ctl_elem_id_get_numid(&info->id);

	/* Set initial value to all of members in all of added elements. */

	data.id = info->id;

	for (i = 0; i < element_count; i++) {

		snd_ctl_elem_id_set_numid(&data.id, numid + i);

		for (j = 0; j < member_count; j++)

			data.value.integer.value[j] = min;

		err = ctl->ops->element_write(ctl, &data);

		if (err < 0)

			return err;

	}

	return 0;

}

/**

 * \brief Create and add some user-defined control elements of integer64 type.

 * \param ctl A handle of backend module for control interface.

 * \param info Common iformation for a new element set, with ID of the first new

 *	       element.

 * \param element_count The number of elements added by this operation.

 * \param member_count The number of members which a element has to

 *	    	   represent its states.

 * \param min Minimum value for each member of the elements.

 * \param max Maximum value for each member of the elements.

 * \param step The step of value for each member in the elements.

 * \return Zero on success, otherwise a negative error code.

 *

 * This function creates some user elements with integer64 type. These elements

 * are not controlled by device drivers in kernel. They can be operated by the

 * same way as usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify new control

 * elements. After returning, all fields of \a id are filled. A element can be

 * identified by the combination of name and index, or by numid.

 *

 * All of members in the new elements are locked. The value of each member is

 * initialized with the minimum value.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A element with ID \a id already exists.

 * 
-EINVAL

 * 
Some arguments include invalid value; i.e. ID has no name, or the number

 *     of members is not between 1 to 127.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user elements.

 * 
-ENXIO

 * 
This backend module does not support user elements of integer64 type.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 *

 * \par Compatibility:

 * This function is added in version 1.1.2.

 */

int snd_ctl_add_integer64_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,

				   unsigned int element_count,

				   unsigned int member_count,

				   long long min, long long max, long long step)

{

	snd_ctl_elem_value_t data = {0};

	unsigned int i;

	unsigned int j;

	unsigned int numid;

	int err;

	if (ctl == NULL || info == NULL || info->id.name[0] == '\0')

		return -EINVAL;

	info->type = SND_CTL_ELEM_TYPE_INTEGER64;

	info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_USER;

	info->owner = element_count;

	info->count = member_count;

	info->value.integer64.min = min;

	info->value.integer64.max = max;

	info->value.integer64.step = step;

	if (!validate_element_member_dimension(info))

		return -EINVAL;

	err = ctl->ops->element_add(ctl, info);

	if (err < 0)

		return err;

	numid = snd_ctl_elem_id_get_numid(&info->id);

	/* Set initial value to all of members in all of added elements. */

	data.id = info->id;

	for (i = 0; i < element_count; i++) {

		snd_ctl_elem_id_set_numid(&data.id, numid + i);

		for (j = 0; j < member_count; j++)

			data.value.integer64.value[j] = min;

		err = ctl->ops->element_write(ctl, &data);

		if (err < 0)

			return err;

	}

	return 0;

}

/**

 * \brief Create and add some user-defined control elements of boolean type.

 * \param ctl A handle of backend module for control interface.

 * \param info Common iformation for a new element set, with ID of the first new

 *	       element.

 * \param element_count The number of elements added by this operation.

 * \param member_count The number of members which a element has to

 *			   represent its states.

 *

 * This function creates some user elements with boolean type. These elements

 * are not controlled by device drivers in kernel. They can be operated by the

 * same way as usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify new control

 * elements. After returning, all fields of \a id are filled. A element can be

 * identified by the combination of name and index, or by numid.

 *

 * All of members in the new elements are locked. The value of each member is

 * initialized with false.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A element with ID \a id already exists.

 * 
-EINVAL

 * 
Some parameters include invalid value; i.e. ID has no name, or the number

 *      of members is not between 1 to 127.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user elements.

 * 
-ENXIO

 * 
This backend module does not support user elements of boolean type.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 *

 * \par Compatibility:

 * This function is added in version 1.1.2.

 */

int snd_ctl_add_boolean_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,

				 unsigned int element_count,

				 unsigned int member_count)

{

	if (ctl == NULL || info == NULL || info->id.name[0] == '\0')

		return -EINVAL;

	info->type = SND_CTL_ELEM_TYPE_BOOLEAN;

	info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_USER;

	info->owner = element_count;

	info->count = member_count;

	info->value.integer.min = 0;

	info->value.integer.max = 1;

	if (!validate_element_member_dimension(info))

		return -EINVAL;

	return ctl->ops->element_add(ctl, info);

}

/**

 * \brief Create and add some user-defined control elements of enumerated type.

 * \param ctl A handle of backend module for control interface.

 * \param info Common iformation for a new element set, with ID of the first new

 *	       element.

 * \param element_count The number of elements added by this operation.

 * \param member_count The number of members which a element has to

 *	    	   represent its states.

 * \param items Range of possible values (0 ... \a items - 1).

 * \param labels An array containing \a items strings.

 * \return Zero on success, otherwise a negative error code.

 *

 * This function creates some user elements with enumerated type. These elements

 * are not controlled by device drivers in kernel. They can be operated by the

 * same way as usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify new control

 * elements. After returning, all fields of \a id are filled. A element can be

 * identified by the combination of name and index, or by numid.

 *

 * All of members in the new elements are locked. The value of each member is

 * initialized with the first entry of labels.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A control element with ID \a id already exists.

 * 
-EINVAL

 * 
Some arguments include invalid value; i.e. \a element_count is not

 *     between 1 to 127, or \a items is not at least one, or a string in \a

 *     labels is empty, or longer than 63 bytes, or total length of the labels

 *     requires more than 64 KiB storage.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user control elements.

 * 
-ENXIO

 * 
This driver does not support (enumerated) user controls.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 *

 * \par Compatibility:

 * This function is added in version 1.1.2.

 */

int snd_ctl_add_enumerated_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,

				    unsigned int element_count,

				    unsigned int member_count,

				    unsigned int items,

				    const char *const labels[])

{

	unsigned int i, bytes;

	char *buf, *p;

	int err;

	if (ctl == NULL || info == NULL || info->id.name[0] == '\0' ||

	    labels == NULL)

		return -EINVAL;

	info->type = SND_CTL_ELEM_TYPE_ENUMERATED;

	info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_USER;

	info->owner = element_count;

	info->count = member_count;

	info->value.enumerated.items = items;

	bytes = 0;

	for (i = 0; i < items; ++i)

		bytes += strlen(labels[i]) + 1;

	if (bytes == 0)

		return -EINVAL;

	buf = malloc(bytes);

	if (buf == NULL)

		return -ENOMEM;

	info->value.enumerated.names_ptr = (uintptr_t)buf;

	info->value.enumerated.names_length = bytes;

	p = buf;

	for (i = 0; i < items; ++i) {

		strcpy(p, labels[i]);

		p += strlen(labels[i]) + 1;

	}

	if (!validate_element_member_dimension(info))

		return -EINVAL;

	err = ctl->ops->element_add(ctl, info);

	free(buf);

	return err;

}

/**

 * \brief Create and add some user-defined control elements of bytes type.

 * \param ctl A handle of backend module for control interface.

 * \param info Common iformation for a new element set, with ID of the first new

 *	       element.

 * \param element_count The number of elements added by this operation.

 * \param member_count The number of members which a element has to

 *			   represent its states.

 * \return Zero on success, otherwise a negative error code.

 *

 * This function creates some user elements with bytes type. These elements are

 * not controlled by device drivers in kernel. They can be operated by the same

 * way as usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify new control

 * elements. After returning, all fields of \a id are filled. A element can be

 * identified by the combination of name and index, or by numid.

 *

 * All of members in the new elements are locked. The value of each member is

 * initialized with the minimum value.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A element with ID \a id already exists.

 * 
-EINVAL

 * 
Some arguments include invalid value; i.e. ID has no name, or the number

 *     of members is not between 1 to 511.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user elements.

 * 
-ENXIO

 * 
This backend module does not support user elements of bytes type.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 *

 * \par Compatibility:

 * This function is added in version 1.1.2.

 */

int snd_ctl_add_bytes_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,

			       unsigned int element_count,

			       unsigned int member_count)

{

	if (ctl == NULL || info == NULL || info->id.name[0] == '\0')

		return -EINVAL;

	info->type = SND_CTL_ELEM_TYPE_BYTES;

	info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |

		       SNDRV_CTL_ELEM_ACCESS_USER;

	info->owner = element_count;

	info->count = member_count;

	if (!validate_element_member_dimension(info))

		return -EINVAL;

	return ctl->ops->element_add(ctl, info);

}

/**

 * \brief Create and add an user-defined control element of integer type.

 *

 * This is a wrapper function to snd_ctl_add_integer_elem_set() for a control

 * element. This doesn't fill the id data with full information, thus it's

 * recommended to use snd_ctl_add_integer_elem_set(), instead.

 */

int snd_ctl_elem_add_integer(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,

			     unsigned int member_count,

			     long min, long max, long step)

{

	snd_ctl_elem_info_t info = {0};

	assert(ctl && id && id->name[0]);

	info.id = *id;

	return snd_ctl_add_integer_elem_set(ctl, &info, 1, member_count,

					    min, max, step);

}

/**

 * \brief Create and add an user-defined control element of integer64 type.

 *

 * This is a wrapper function to snd_ctl_add_integer64_elem_set() for a single

 * control element. This doesn't fill the id data with full information, thus

 * it's recommended to use snd_ctl_add_integer64_elem_set(), instead.

 */

int snd_ctl_elem_add_integer64(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,

			       unsigned int member_count,

			       long long min, long long max, long long step)

{

	snd_ctl_elem_info_t info = {0};

	assert(ctl && id && id->name[0]);

	info.id = *id;

	return snd_ctl_add_integer64_elem_set(ctl, &info, 1, member_count,

					      min, max, step);

}

/**

 * \brief Create and add an user-defined control element of boolean type.

 *

 * This is a wrapper function to snd_ctl_add_boolean_elem_set() for a single

 * control element. This doesn't fill the id data with full information, thus

 * it's recommended to use snd_ctl_add_boolean_elem_set(), instead.

 */

int snd_ctl_elem_add_boolean(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,

			     unsigned int member_count)

{

	snd_ctl_elem_info_t info = {0};

	assert(ctl && id && id->name[0]);

	info.id = *id;

	return snd_ctl_add_boolean_elem_set(ctl, &info, 1, member_count);

}

/**

 * \brief Create and add a user-defined control element of enumerated type.

 *

 * This is a wrapper function to snd_ctl_add_enumerated_elem_set() for a single

 * control element. This doesn't fill the id data with full information, thus

 * it's recommended to use snd_ctl_add_enumerated_elem_set(), instead.

 *

 * This function is added in version 1.0.25.

 */

int snd_ctl_elem_add_enumerated(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,

				unsigned int member_count, unsigned int items,

				const char *const labels[])

{

	snd_ctl_elem_info_t info = {0};

	assert(ctl && id && id->name[0] && labels);

	info.id = *id;

	return snd_ctl_add_enumerated_elem_set(ctl, &info, 1, member_count,

					       items, labels);

}

/**

 * \brief Create and add a user-defined control element of IEC958 type.

 * \param[in] ctl A handle of backend module for control interface.

 * \param[in,out] id ID of the new control element.

 *

 * This function creates an user element with IEC958 type. This element is not

 * controlled by device drivers in kernel. It can be operated by the same way as

 * usual elements added by the device drivers.

 *

 * The name field of \a id must be set with unique value to identify a new

 * control element. After returning, all fields of \a id are filled. A element

 * can be identified by the combination of name and index, or by numid.

 *

 * A member in the new element is locked and filled with zero.

 *

 * \par Errors:

 * 

 * 
-EBUSY

 * 
A control element with ID \a id already exists.

 * 
-EINVAL

 * 
ID has no name.

 * 
-ENOMEM

 * 
Out of memory, or there are too many user elements.

 * 
-ENXIO

 * 
This backend module does not support user elements of IEC958 type.

 * 
-ENODEV

 * 
Device unplugged.

 * 

 */

int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id)

{

	snd_ctl_elem_info_t info = {0};

	assert(ctl && id && id->name[0]);

	info.id = *id;

	info.type = SND_CTL_ELEM_TYPE_IEC958;

	info.owner = 1;

	info.count = 1;

	return ctl->ops->element_add(ctl, &info;;

}

/**

 * \brief Remove an user CTL element

 * \param ctl CTL handle

 * \param id CTL element identification

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)

{

	assert(ctl && id && (id->name[0] || id->numid));

	return ctl->ops->element_remove(ctl, id);

}

/**

 * \brief Get CTL element value

 * \param ctl CTL handle

 * \param data Data of an element.

 * \return 0 on success otherwise a negative error code

 */

int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data)

{

	assert(ctl && data && (data->id.name[0] || data->id.numid));