"Fossies" - the Fresh Open Source Software Archive

Member "alsa-lib-1.1.9/src/control/control.c" (10 May 2019, 86529 Bytes) of package /linux/misc/alsa-lib-1.1.9.tar.bz2:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "control.c" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.1.8_vs_1.1.9.

    1 /**
    2  * \file control/control.c
    3  * \brief CTL interface - primitive controls
    4  * \author Abramo Bagnara <abramo@alsa-project.org>
    5  * \date 2000
    6  *
    7  * CTL interface is designed to access primitive controls.
    8  * See \ref control page for more details.
    9  */
   10 /*
   11  *  Control Interface - main file
   12  *  Copyright (c) 2000 by Abramo Bagnara <abramo@alsa-project.org>
   13  *
   14  *
   15  *   This library is free software; you can redistribute it and/or modify
   16  *   it under the terms of the GNU Lesser General Public License as
   17  *   published by the Free Software Foundation; either version 2.1 of
   18  *   the License, or (at your option) any later version.
   19  *
   20  *   This program is distributed in the hope that it will be useful,
   21  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
   22  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   23  *   GNU Lesser General Public License for more details.
   24  *
   25  *   You should have received a copy of the GNU Lesser General Public
   26  *   License along with this library; if not, write to the Free Software
   27  *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
   28  *
   29  */
   30 
   31 /*! \page control Control interface
   32 
   33 <P>Control interface is designed to access primitive controls. There is
   34 also interface notifying about control and structure changes.
   35 
   36 \section control_general_overview General overview
   37 
   38 In ALSA control feature, each sound card can have control elements. The elements
   39 are managed according to below model.
   40 
   41  - element set
   42    - A set of elements with the same attribute (i.e. name, get/put operations).
   43      Some element sets can be added to a sound card by drivers in kernel and
   44      userspace applications.
   45  - element
   46    - An element can be identified by userspace applications. Each element has
   47      own identical information.
   48  - member
   49    - An element includes some members to have a value. The value of each member
   50      can be changed by both of userspace applications and drivers in kernel.
   51 
   52 Each element can be identified by two ways; a combination of name and index, or
   53 numerical number (numid).
   54 
   55 The type of element set is one of integer, integerr64, boolean, enumerators,
   56 bytes and IEC958 structure. This indicates the type of value for each member in
   57 elements included in the element set.
   58 
   59 When the value of member is changed, corresponding events are transferred to
   60 userspace applications. The applications should subscribe any events in advance.
   61 
   62 \section tlv_blob Supplemental data for elements in an element set
   63 
   64 TLV feature is designed to transfer data in a shape of Type/Length/Value,
   65 between a driver and any userspace applications. The main purpose is to attach
   66 supplement information for elements to an element set; e.g. dB range.
   67 
   68 At first, this feature was implemented to add pre-defined data readable to
   69 userspace applications. Soon, it was extended to handle several operations;
   70 read, write and command. The original implementation remains as the read
   71 operation. The command operation allows drivers to have own implementations
   72 against requests from userspace applications.
   73 
   74 This feature was introduced to ALSA control feature in 2006, at commit
   75 c7a0708a2362, corresponding to a series of work for Linux kernel (42750b04c5ba
   76 and 8aa9b586e420).
   77 
   78 There's no limitation about maximum size of the data, therefore it can be used
   79 to deliver quite large arbitrary data from userspace to in-kernel drivers via
   80 ALSA control character device. Focusing on this nature, as of 2016, some
   81 in-kernel implementations utilize this feature for I/O operations. This is
   82 against the original design.
   83 */
   84 
   85 #include <stdio.h>
   86 #include <stdlib.h>
   87 #include <stdint.h>
   88 #include <stdarg.h>
   89 #include <unistd.h>
   90 #include <string.h>
   91 #include <fcntl.h>
   92 #include <signal.h>
   93 #include <poll.h>
   94 #include <stdbool.h>
   95 #include "control_local.h"
   96 
   97 /**
   98  * \brief get identifier of CTL handle
   99  * \param ctl CTL handle
  100  * \return ascii identifier of CTL handle
  101  *
  102  * Returns the ASCII identifier of given CTL handle. It's the same
  103  * identifier specified in snd_ctl_open().
  104  */
  105 const char *snd_ctl_name(snd_ctl_t *ctl)
  106 {
  107     assert(ctl);
  108     return ctl->name;
  109 }
  110 
  111 /**
  112  * \brief get type of CTL handle
  113  * \param ctl CTL handle
  114  * \return type of CTL handle
  115  *
  116  * Returns the type #snd_ctl_type_t of given CTL handle.
  117  */
  118 snd_ctl_type_t snd_ctl_type(snd_ctl_t *ctl)
  119 {
  120     assert(ctl);
  121     return ctl->type;
  122 }
  123 
  124 /**
  125  * \brief close CTL handle
  126  * \param ctl CTL handle
  127  * \return 0 on success otherwise a negative error code
  128  *
  129  * Closes the specified CTL handle and frees all associated
  130  * resources.
  131  */
  132 int snd_ctl_close(snd_ctl_t *ctl)
  133 {
  134     int err;
  135     while (!list_empty(&ctl->async_handlers)) {
  136         snd_async_handler_t *h = list_entry(&ctl->async_handlers.next, snd_async_handler_t, hlist);
  137         snd_async_del_handler(h);
  138     }
  139     err = ctl->ops->close(ctl);
  140     free(ctl->name);
  141     snd_dlobj_cache_put(ctl->open_func);
  142     free(ctl);
  143     return err;
  144 }
  145 
  146 /**
  147  * \brief set nonblock mode
  148  * \param ctl CTL handle
  149  * \param nonblock 0 = block, 1 = nonblock mode, 2 = abort
  150  * \return 0 on success otherwise a negative error code
  151  */
  152 int snd_ctl_nonblock(snd_ctl_t *ctl, int nonblock)
  153 {
  154     int err;
  155     assert(ctl);
  156     err = ctl->ops->nonblock(ctl, nonblock);
  157     if (err < 0)
  158         return err;
  159     ctl->nonblock = nonblock;
  160     return 0;
  161 }
  162 
  163 #ifndef DOC_HIDDEN
  164 int snd_ctl_new(snd_ctl_t **ctlp, snd_ctl_type_t type, const char *name)
  165 {
  166     snd_ctl_t *ctl;
  167     ctl = calloc(1, sizeof(*ctl));
  168     if (!ctl)
  169         return -ENOMEM;
  170     ctl->type = type;
  171     if (name)
  172         ctl->name = strdup(name);
  173     INIT_LIST_HEAD(&ctl->async_handlers);
  174     *ctlp = ctl;
  175     return 0;
  176 }
  177     
  178 
  179 /**
  180  * \brief set async mode
  181  * \param ctl CTL handle
  182  * \param sig Signal to raise: < 0 disable, 0 default (SIGIO)
  183  * \param pid Process ID to signal: 0 current
  184  * \return 0 on success otherwise a negative error code
  185  *
  186  * A signal is raised when a change happens.
  187  */
  188 int snd_ctl_async(snd_ctl_t *ctl, int sig, pid_t pid)
  189 {
  190     assert(ctl);
  191     if (sig == 0)
  192         sig = SIGIO;
  193     if (pid == 0)
  194         pid = getpid();
  195     return ctl->ops->async(ctl, sig, pid);
  196 }
  197 #endif
  198 
  199 /**
  200  * \brief get count of poll descriptors for CTL handle
  201  * \param ctl CTL handle
  202  * \return count of poll descriptors
  203  */
  204 int snd_ctl_poll_descriptors_count(snd_ctl_t *ctl)
  205 {
  206     assert(ctl);
  207     if (ctl->ops->poll_descriptors_count)
  208         return ctl->ops->poll_descriptors_count(ctl);
  209     if (ctl->poll_fd < 0)
  210         return 0;
  211     return 1;
  212 }
  213 
  214 /**
  215  * \brief get poll descriptors
  216  * \param ctl CTL handle
  217  * \param pfds array of poll descriptors
  218  * \param space space in the poll descriptor array
  219  * \return count of filled descriptors
  220  */
  221 int snd_ctl_poll_descriptors(snd_ctl_t *ctl, struct pollfd *pfds, unsigned int space)
  222 {
  223     assert(ctl && pfds);
  224     if (ctl->ops->poll_descriptors)
  225         return ctl->ops->poll_descriptors(ctl, pfds, space);
  226     if (ctl->poll_fd < 0)
  227         return 0;
  228     if (space > 0) {
  229         pfds->fd = ctl->poll_fd;
  230         pfds->events = POLLIN|POLLERR|POLLNVAL;
  231         return 1;
  232     }
  233     return 0;
  234 }
  235 
  236 /**
  237  * \brief get returned events from poll descriptors
  238  * \param ctl CTL handle
  239  * \param pfds array of poll descriptors
  240  * \param nfds count of poll descriptors
  241  * \param revents returned events
  242  * \return zero if success, otherwise a negative error code
  243  */
  244 int snd_ctl_poll_descriptors_revents(snd_ctl_t *ctl, struct pollfd *pfds, unsigned int nfds, unsigned short *revents)
  245 {
  246     assert(ctl && pfds && revents);
  247     if (ctl->ops->poll_revents)
  248         return ctl->ops->poll_revents(ctl, pfds, nfds, revents);
  249     if (nfds == 1) {
  250         *revents = pfds->revents;
  251                 return 0;
  252     }
  253     return -EINVAL;
  254 }
  255 
  256 /**
  257  * \brief Ask to be informed about events (poll, #snd_async_add_ctl_handler, #snd_ctl_read)
  258  * \param ctl CTL handle
  259  * \param subscribe 0 = unsubscribe, 1 = subscribe, -1 = check subscribe or not
  260  * \return 0 on success otherwise a negative error code
  261  */
  262 int snd_ctl_subscribe_events(snd_ctl_t *ctl, int subscribe)
  263 {
  264     assert(ctl);
  265     return ctl->ops->subscribe_events(ctl, subscribe);
  266 }
  267 
  268 
  269 /**
  270  * \brief Get card related information
  271  * \param ctl CTL handle
  272  * \param info Card info pointer
  273  * \return 0 on success otherwise a negative error code
  274  */
  275 int snd_ctl_card_info(snd_ctl_t *ctl, snd_ctl_card_info_t *info)
  276 {
  277     assert(ctl && info);
  278     return ctl->ops->card_info(ctl, info);
  279 }
  280 
  281 /**
  282  * \brief Get a list of element identifiers
  283  * \param ctl CTL handle
  284  * \param list CTL element identifiers list pointer
  285  * \return 0 on success otherwise a negative error code
  286  */
  287 int snd_ctl_elem_list(snd_ctl_t *ctl, snd_ctl_elem_list_t *list)
  288 {
  289     assert(ctl && list);
  290     assert(list->space == 0 || list->pids);
  291     return ctl->ops->element_list(ctl, list);
  292 }
  293 
  294 /**
  295  * \brief Get CTL element information
  296  * \param ctl CTL handle
  297  * \param info CTL element id/information pointer
  298  * \return 0 on success otherwise a negative error code
  299  */
  300 int snd_ctl_elem_info(snd_ctl_t *ctl, snd_ctl_elem_info_t *info)
  301 {
  302     assert(ctl && info && (info->id.name[0] || info->id.numid));
  303     return ctl->ops->element_info(ctl, info);
  304 }
  305 
  306 static bool validate_element_member_dimension(snd_ctl_elem_info_t *info)
  307 {
  308     unsigned int members;
  309     unsigned int i;
  310 
  311     if (info->dimen.d[0] == 0)
  312         return true;
  313 
  314     members = 1;
  315     for (i = 0; i < ARRAY_SIZE(info->dimen.d); ++i) {
  316         if (info->dimen.d[i] == 0)
  317             break;
  318         members *= info->dimen.d[i];
  319 
  320         if (members > info->count)
  321             return false;
  322     }
  323 
  324     for (++i; i < ARRAY_SIZE(info->dimen.d); ++i) {
  325         if (info->dimen.d[i] > 0)
  326             return false;
  327     }
  328 
  329     return members == info->count;
  330 }
  331 
  332 /**
  333  * \brief Create and add some user-defined control elements of integer type.
  334  * \param ctl A handle of backend module for control interface.
  335  * \param info Common iformation for a new element set, with ID of the first new
  336  *         element.
  337  * \param element_count The number of elements added by this operation.
  338  * \param member_count The number of members which a element has to
  339  *             represent its states.
  340  * \param min Minimum value for each member of the elements.
  341  * \param max Maximum value for each member of the elements.
  342  * \param step The step of value for each member in the elements.
  343  * \return Zero on success, otherwise a negative error code.
  344  *
  345  * This function creates some user elements with integer type. These elements
  346  * are not controlled by device drivers in kernel. They can be operated by the
  347  * same way as usual elements added by the device drivers.
  348  *
  349  * The name field of \a id must be set with unique value to identify new control
  350  * elements. After returning, all fields of \a id are filled. A element can be
  351  * identified by the combination of name and index, or by numid.
  352  *
  353  * All of members in the new elements are locked. The value of each member is
  354  * initialized with the minimum value.
  355  *
  356  * \par Errors:
  357  * <dl>
  358  * <dt>-EBUSY
  359  * <dd>A element with ID \a id already exists.
  360  * <dt>-EINVAL
  361  * <dd>Some arguments include invalid value; i.e. ID field in \a info has no
  362  *     name, or the number of members is not between 1 to 127.
  363  * <dt>-ENOMEM
  364  * <dd>Out of memory, or there are too many user elements.
  365  * <dt>-ENXIO
  366  * <dd>This backend module does not support user elements of integer type.
  367  * <dt>-ENODEV
  368  * <dd>Device unplugged.
  369  * </dl>
  370  *
  371  * \par Compatibility:
  372  * This function is added in version 1.1.2.
  373  */
  374 int snd_ctl_add_integer_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
  375                  unsigned int element_count,
  376                  unsigned int member_count,
  377                  long min, long max, long step)
  378 {
  379     snd_ctl_elem_value_t data = {0};
  380     unsigned int i;
  381     unsigned int j;
  382     unsigned int numid;
  383     int err;
  384 
  385     if (ctl == NULL || info == NULL || info->id.name[0] == '\0')
  386         return -EINVAL;
  387 
  388     info->type = SND_CTL_ELEM_TYPE_INTEGER;
  389     info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
  390                SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |
  391                SNDRV_CTL_ELEM_ACCESS_USER;
  392     info->owner = element_count;
  393     info->count = member_count;
  394     info->value.integer.min = min;
  395     info->value.integer.max = max;
  396     info->value.integer.step = step;
  397 
  398     if (!validate_element_member_dimension(info))
  399         return -EINVAL;
  400 
  401     err = ctl->ops->element_add(ctl, info);
  402     if (err < 0)
  403         return err;
  404     numid = snd_ctl_elem_id_get_numid(&info->id);
  405 
  406     /* Set initial value to all of members in all of added elements. */
  407     data.id = info->id;
  408     for (i = 0; i < element_count; i++) {
  409         snd_ctl_elem_id_set_numid(&data.id, numid + i);
  410 
  411         for (j = 0; j < member_count; j++)
  412             data.value.integer.value[j] = min;
  413 
  414         err = ctl->ops->element_write(ctl, &data);
  415         if (err < 0)
  416             return err;
  417     }
  418 
  419     return 0;
  420 }
  421 
  422 /**
  423  * \brief Create and add some user-defined control elements of integer64 type.
  424  * \param ctl A handle of backend module for control interface.
  425  * \param info Common iformation for a new element set, with ID of the first new
  426  *         element.
  427  * \param element_count The number of elements added by this operation.
  428  * \param member_count The number of members which a element has to
  429  *             represent its states.
  430  * \param min Minimum value for each member of the elements.
  431  * \param max Maximum value for each member of the elements.
  432  * \param step The step of value for each member in the elements.
  433  * \return Zero on success, otherwise a negative error code.
  434  *
  435  * This function creates some user elements with integer64 type. These elements
  436  * are not controlled by device drivers in kernel. They can be operated by the
  437  * same way as usual elements added by the device drivers.
  438  *
  439  * The name field of \a id must be set with unique value to identify new control
  440  * elements. After returning, all fields of \a id are filled. A element can be
  441  * identified by the combination of name and index, or by numid.
  442  *
  443  * All of members in the new elements are locked. The value of each member is
  444  * initialized with the minimum value.
  445  *
  446  * \par Errors:
  447  * <dl>
  448  * <dt>-EBUSY
  449  * <dd>A element with ID \a id already exists.
  450  * <dt>-EINVAL
  451  * <dd>Some arguments include invalid value; i.e. ID has no name, or the number
  452  *     of members is not between 1 to 127.
  453  * <dt>-ENOMEM
  454  * <dd>Out of memory, or there are too many user elements.
  455  * <dt>-ENXIO
  456  * <dd>This backend module does not support user elements of integer64 type.
  457  * <dt>-ENODEV
  458  * <dd>Device unplugged.
  459  * </dl>
  460  *
  461  * \par Compatibility:
  462  * This function is added in version 1.1.2.
  463  */
  464 int snd_ctl_add_integer64_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
  465                    unsigned int element_count,
  466                    unsigned int member_count,
  467                    long long min, long long max, long long step)
  468 {
  469     snd_ctl_elem_value_t data = {0};
  470     unsigned int i;
  471     unsigned int j;
  472     unsigned int numid;
  473     int err;
  474 
  475     if (ctl == NULL || info == NULL || info->id.name[0] == '\0')
  476         return -EINVAL;
  477 
  478     info->type = SND_CTL_ELEM_TYPE_INTEGER64;
  479     info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
  480                SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |
  481                SNDRV_CTL_ELEM_ACCESS_USER;
  482     info->owner = element_count;
  483     info->count = member_count;
  484     info->value.integer64.min = min;
  485     info->value.integer64.max = max;
  486     info->value.integer64.step = step;
  487 
  488     if (!validate_element_member_dimension(info))
  489         return -EINVAL;
  490 
  491     err = ctl->ops->element_add(ctl, info);
  492     if (err < 0)
  493         return err;
  494     numid = snd_ctl_elem_id_get_numid(&info->id);
  495 
  496     /* Set initial value to all of members in all of added elements. */
  497     data.id = info->id;
  498     for (i = 0; i < element_count; i++) {
  499         snd_ctl_elem_id_set_numid(&data.id, numid + i);
  500 
  501         for (j = 0; j < member_count; j++)
  502             data.value.integer64.value[j] = min;
  503 
  504         err = ctl->ops->element_write(ctl, &data);
  505         if (err < 0)
  506             return err;
  507     }
  508 
  509     return 0;
  510 }
  511 
  512 /**
  513  * \brief Create and add some user-defined control elements of boolean type.
  514  * \param ctl A handle of backend module for control interface.
  515  * \param info Common iformation for a new element set, with ID of the first new
  516  *         element.
  517  * \param element_count The number of elements added by this operation.
  518  * \param member_count The number of members which a element has to
  519  *             represent its states.
  520  *
  521  * This function creates some user elements with boolean type. These elements
  522  * are not controlled by device drivers in kernel. They can be operated by the
  523  * same way as usual elements added by the device drivers.
  524  *
  525  * The name field of \a id must be set with unique value to identify new control
  526  * elements. After returning, all fields of \a id are filled. A element can be
  527  * identified by the combination of name and index, or by numid.
  528  *
  529  * All of members in the new elements are locked. The value of each member is
  530  * initialized with false.
  531  *
  532  * \par Errors:
  533  * <dl>
  534  * <dt>-EBUSY
  535  * <dd>A element with ID \a id already exists.
  536  * <dt>-EINVAL
  537  * <dd>Some parameters include invalid value; i.e. ID has no name, or the number
  538  *      of members is not between 1 to 127.
  539  * <dt>-ENOMEM
  540  * <dd>Out of memory, or there are too many user elements.
  541  * <dt>-ENXIO
  542  * <dd>This backend module does not support user elements of boolean type.
  543  * <dt>-ENODEV
  544  * <dd>Device unplugged.
  545  * </dl>
  546  *
  547  * \par Compatibility:
  548  * This function is added in version 1.1.2.
  549  */
  550 int snd_ctl_add_boolean_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
  551                  unsigned int element_count,
  552                  unsigned int member_count)
  553 {
  554     if (ctl == NULL || info == NULL || info->id.name[0] == '\0')
  555         return -EINVAL;
  556 
  557     info->type = SND_CTL_ELEM_TYPE_BOOLEAN;
  558     info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
  559                SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |
  560                SNDRV_CTL_ELEM_ACCESS_USER;
  561     info->owner = element_count;
  562     info->count = member_count;
  563     info->value.integer.min = 0;
  564     info->value.integer.max = 1;
  565 
  566     if (!validate_element_member_dimension(info))
  567         return -EINVAL;
  568 
  569     return ctl->ops->element_add(ctl, info);
  570 }
  571 
  572 /**
  573  * \brief Create and add some user-defined control elements of enumerated type.
  574  * \param ctl A handle of backend module for control interface.
  575  * \param info Common iformation for a new element set, with ID of the first new
  576  *         element.
  577  * \param element_count The number of elements added by this operation.
  578  * \param member_count The number of members which a element has to
  579  *             represent its states.
  580  * \param items Range of possible values (0 ... \a items - 1).
  581  * \param labels An array containing \a items strings.
  582  * \return Zero on success, otherwise a negative error code.
  583  *
  584  * This function creates some user elements with enumerated type. These elements
  585  * are not controlled by device drivers in kernel. They can be operated by the
  586  * same way as usual elements added by the device drivers.
  587  *
  588  * The name field of \a id must be set with unique value to identify new control
  589  * elements. After returning, all fields of \a id are filled. A element can be
  590  * identified by the combination of name and index, or by numid.
  591  *
  592  * All of members in the new elements are locked. The value of each member is
  593  * initialized with the first entry of labels.
  594  *
  595  * \par Errors:
  596  * <dl>
  597  * <dt>-EBUSY
  598  * <dd>A control element with ID \a id already exists.
  599  * <dt>-EINVAL
  600  * <dd>Some arguments include invalid value; i.e. \a element_count is not
  601  *     between 1 to 127, or \a items is not at least one, or a string in \a
  602  *     labels is empty, or longer than 63 bytes, or total length of the labels
  603  *     requires more than 64 KiB storage.
  604  * <dt>-ENOMEM
  605  * <dd>Out of memory, or there are too many user control elements.
  606  * <dt>-ENXIO
  607  * <dd>This driver does not support (enumerated) user controls.
  608  * <dt>-ENODEV
  609  * <dd>Device unplugged.
  610  * </dl>
  611  *
  612  * \par Compatibility:
  613  * This function is added in version 1.1.2.
  614  */
  615 int snd_ctl_add_enumerated_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
  616                     unsigned int element_count,
  617                     unsigned int member_count,
  618                     unsigned int items,
  619                     const char *const labels[])
  620 {
  621     unsigned int i, bytes;
  622     char *buf, *p;
  623     int err;
  624 
  625     if (ctl == NULL || info == NULL || info->id.name[0] == '\0' ||
  626         labels == NULL)
  627         return -EINVAL;
  628 
  629     info->type = SND_CTL_ELEM_TYPE_ENUMERATED;
  630     info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
  631                SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |
  632                SNDRV_CTL_ELEM_ACCESS_USER;
  633     info->owner = element_count;
  634     info->count = member_count;
  635     info->value.enumerated.items = items;
  636 
  637     bytes = 0;
  638     for (i = 0; i < items; ++i)
  639         bytes += strlen(labels[i]) + 1;
  640     if (bytes == 0)
  641         return -EINVAL;
  642     buf = malloc(bytes);
  643     if (buf == NULL)
  644         return -ENOMEM;
  645     info->value.enumerated.names_ptr = (uintptr_t)buf;
  646     info->value.enumerated.names_length = bytes;
  647     p = buf;
  648     for (i = 0; i < items; ++i) {
  649         strcpy(p, labels[i]);
  650         p += strlen(labels[i]) + 1;
  651     }
  652 
  653     if (!validate_element_member_dimension(info))
  654         return -EINVAL;
  655 
  656     err = ctl->ops->element_add(ctl, info);
  657 
  658     free(buf);
  659 
  660     return err;
  661 }
  662 
  663 /**
  664  * \brief Create and add some user-defined control elements of bytes type.
  665  * \param ctl A handle of backend module for control interface.
  666  * \param info Common iformation for a new element set, with ID of the first new
  667  *         element.
  668  * \param element_count The number of elements added by this operation.
  669  * \param member_count The number of members which a element has to
  670  *             represent its states.
  671  * \return Zero on success, otherwise a negative error code.
  672  *
  673  * This function creates some user elements with bytes type. These elements are
  674  * not controlled by device drivers in kernel. They can be operated by the same
  675  * way as usual elements added by the device drivers.
  676  *
  677  * The name field of \a id must be set with unique value to identify new control
  678  * elements. After returning, all fields of \a id are filled. A element can be
  679  * identified by the combination of name and index, or by numid.
  680  *
  681  * All of members in the new elements are locked. The value of each member is
  682  * initialized with the minimum value.
  683  *
  684  * \par Errors:
  685  * <dl>
  686  * <dt>-EBUSY
  687  * <dd>A element with ID \a id already exists.
  688  * <dt>-EINVAL
  689  * <dd>Some arguments include invalid value; i.e. ID has no name, or the number
  690  *     of members is not between 1 to 511.
  691  * <dt>-ENOMEM
  692  * <dd>Out of memory, or there are too many user elements.
  693  * <dt>-ENXIO
  694  * <dd>This backend module does not support user elements of bytes type.
  695  * <dt>-ENODEV
  696  * <dd>Device unplugged.
  697  * </dl>
  698  *
  699  * \par Compatibility:
  700  * This function is added in version 1.1.2.
  701  */
  702 int snd_ctl_add_bytes_elem_set(snd_ctl_t *ctl, snd_ctl_elem_info_t *info,
  703                    unsigned int element_count,
  704                    unsigned int member_count)
  705 {
  706     if (ctl == NULL || info == NULL || info->id.name[0] == '\0')
  707         return -EINVAL;
  708 
  709     info->type = SND_CTL_ELEM_TYPE_BYTES;
  710     info->access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
  711                SNDRV_CTL_ELEM_ACCESS_TLV_READWRITE |
  712                SNDRV_CTL_ELEM_ACCESS_USER;
  713     info->owner = element_count;
  714     info->count = member_count;
  715 
  716     if (!validate_element_member_dimension(info))
  717         return -EINVAL;
  718 
  719     return ctl->ops->element_add(ctl, info);
  720 }
  721 
  722 /**
  723  * \brief Create and add an user-defined control element of integer type.
  724  *
  725  * This is a wrapper function to snd_ctl_add_integer_elem_set() for a control
  726  * element. This doesn't fill the id data with full information, thus it's
  727  * recommended to use snd_ctl_add_integer_elem_set(), instead.
  728  */
  729 int snd_ctl_elem_add_integer(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  730                  unsigned int member_count,
  731                  long min, long max, long step)
  732 {
  733     snd_ctl_elem_info_t info = {0};
  734 
  735     assert(ctl && id && id->name[0]);
  736 
  737     info.id = *id;
  738 
  739     return snd_ctl_add_integer_elem_set(ctl, &info, 1, member_count,
  740                         min, max, step);
  741 }
  742 
  743 /**
  744  * \brief Create and add an user-defined control element of integer64 type.
  745  *
  746  * This is a wrapper function to snd_ctl_add_integer64_elem_set() for a single
  747  * control element. This doesn't fill the id data with full information, thus
  748  * it's recommended to use snd_ctl_add_integer64_elem_set(), instead.
  749  */
  750 int snd_ctl_elem_add_integer64(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  751                    unsigned int member_count,
  752                    long long min, long long max, long long step)
  753 {
  754     snd_ctl_elem_info_t info = {0};
  755 
  756     assert(ctl && id && id->name[0]);
  757 
  758     info.id = *id;
  759 
  760     return snd_ctl_add_integer64_elem_set(ctl, &info, 1, member_count,
  761                           min, max, step);
  762 }
  763 
  764 /**
  765  * \brief Create and add an user-defined control element of boolean type.
  766  *
  767  * This is a wrapper function to snd_ctl_add_boolean_elem_set() for a single
  768  * control element. This doesn't fill the id data with full information, thus
  769  * it's recommended to use snd_ctl_add_boolean_elem_set(), instead.
  770  */
  771 int snd_ctl_elem_add_boolean(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  772                  unsigned int member_count)
  773 {
  774     snd_ctl_elem_info_t info = {0};
  775 
  776     assert(ctl && id && id->name[0]);
  777 
  778     info.id = *id;
  779 
  780     return snd_ctl_add_boolean_elem_set(ctl, &info, 1, member_count);
  781 }
  782 
  783 /**
  784  * \brief Create and add a user-defined control element of enumerated type.
  785  *
  786  * This is a wrapper function to snd_ctl_add_enumerated_elem_set() for a single
  787  * control element. This doesn't fill the id data with full information, thus
  788  * it's recommended to use snd_ctl_add_enumerated_elem_set(), instead.
  789  *
  790  * This function is added in version 1.0.25.
  791  */
  792 int snd_ctl_elem_add_enumerated(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  793                 unsigned int member_count, unsigned int items,
  794                 const char *const labels[])
  795 {
  796     snd_ctl_elem_info_t info = {0};
  797 
  798     assert(ctl && id && id->name[0] && labels);
  799 
  800     info.id = *id;
  801 
  802     return snd_ctl_add_enumerated_elem_set(ctl, &info, 1, member_count,
  803                            items, labels);
  804 }
  805 
  806 /**
  807  * \brief Create and add a user-defined control element of IEC958 type.
  808  * \param[in] ctl A handle of backend module for control interface.
  809  * \param[in,out] id ID of the new control element.
  810  *
  811  * This function creates an user element with IEC958 type. This element is not
  812  * controlled by device drivers in kernel. It can be operated by the same way as
  813  * usual elements added by the device drivers.
  814  *
  815  * The name field of \a id must be set with unique value to identify a new
  816  * control element. After returning, all fields of \a id are filled. A element
  817  * can be identified by the combination of name and index, or by numid.
  818  *
  819  * A member in the new element is locked and filled with zero.
  820  *
  821  * \par Errors:
  822  * <dl>
  823  * <dt>-EBUSY
  824  * <dd>A control element with ID \a id already exists.
  825  * <dt>-EINVAL
  826  * <dd>ID has no name.
  827  * <dt>-ENOMEM
  828  * <dd>Out of memory, or there are too many user elements.
  829  * <dt>-ENXIO
  830  * <dd>This backend module does not support user elements of IEC958 type.
  831  * <dt>-ENODEV
  832  * <dd>Device unplugged.
  833  * </dl>
  834  */
  835 int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id)
  836 {
  837     snd_ctl_elem_info_t info = {0};
  838 
  839     assert(ctl && id && id->name[0]);
  840 
  841     info.id = *id;
  842     info.type = SND_CTL_ELEM_TYPE_IEC958;
  843     info.owner = 1;
  844     info.count = 1;
  845     return ctl->ops->element_add(ctl, &info);
  846 }
  847 
  848 /**
  849  * \brief Remove an user CTL element
  850  * \param ctl CTL handle
  851  * \param id CTL element identification
  852  * \return 0 on success otherwise a negative error code
  853  */
  854 int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
  855 {
  856     assert(ctl && id && (id->name[0] || id->numid));
  857     return ctl->ops->element_remove(ctl, id);
  858 }
  859 
  860 /**
  861  * \brief Get CTL element value
  862  * \param ctl CTL handle
  863  * \param data Data of an element.
  864  * \return 0 on success otherwise a negative error code
  865  */
  866 int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
  867 {
  868     assert(ctl && data && (data->id.name[0] || data->id.numid));
  869     return ctl->ops->element_read(ctl, data);
  870 }
  871 
  872 /**
  873  * \brief Set CTL element value
  874  * \param ctl CTL handle
  875  * \param data Data of an element.
  876  * \retval 0 on success
  877  * \retval >0 on success when value was changed
  878  * \retval <0 a negative error code
  879  */
  880 int snd_ctl_elem_write(snd_ctl_t *ctl, snd_ctl_elem_value_t *data)
  881 {
  882     assert(ctl && data && (data->id.name[0] || data->id.numid));
  883     return ctl->ops->element_write(ctl, data);
  884 }
  885 
  886 static int snd_ctl_tlv_do(snd_ctl_t *ctl, int op_flag,
  887               const snd_ctl_elem_id_t *id,
  888                   unsigned int *tlv, unsigned int tlv_size)
  889 {
  890     snd_ctl_elem_info_t *info = NULL;
  891     int err;
  892 
  893     if (id->numid == 0) {
  894         info = calloc(1, sizeof(*info));
  895         if (info == NULL)
  896             return -ENOMEM;
  897         info->id = *id;
  898         id = &info->id;
  899         err = snd_ctl_elem_info(ctl, info);
  900         if (err < 0)
  901             goto __err;
  902         if (id->numid == 0) {
  903             err = -ENOENT;
  904             goto __err;
  905         }
  906     }
  907     err = ctl->ops->element_tlv(ctl, op_flag, id->numid, tlv, tlv_size);
  908       __err:
  909         if (info)
  910             free(info);
  911     return err;
  912 }
  913 
  914 /**
  915  * \brief Read structured data from an element set to given buffer.
  916  * \param ctl A handle of backend module for control interface.
  917  * \param id ID of an element.
  918  * \param tlv An array with members of unsigned int type.
  919  * \param tlv_size The length of the array.
  920  * \return 0 on success otherwise a negative error code
  921  *
  922  * The format of an array of \a tlv argument is:
  923  *   tlv[0]:   Type. One of SND_CTL_TLVT_XXX.
  924  *   tlv[1]:   Length. The length of value in units of byte.
  925  *   tlv[2..]: Value. Depending on the type.
  926  *
  927  * Details are described in <sound/tlv.h>.
  928  */
  929 int snd_ctl_elem_tlv_read(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  930               unsigned int *tlv, unsigned int tlv_size)
  931 {
  932     int err;
  933     assert(ctl && id && (id->name[0] || id->numid) && tlv);
  934     if (tlv_size < 2 * sizeof(int))
  935         return -EINVAL;
  936     /* 1.0.12 driver doesn't return the error even if the user TLV
  937      * is empty.  So, initialize TLV here with an invalid type
  938      * and compare the returned value after ioctl for checking
  939      * the validity of TLV.
  940      */
  941     tlv[SNDRV_CTL_TLVO_TYPE] = -1;
  942     tlv[SNDRV_CTL_TLVO_LEN] = 0;
  943     err = snd_ctl_tlv_do(ctl, 0, id, tlv, tlv_size);
  944     if (err >= 0 && tlv[SNDRV_CTL_TLVO_TYPE] == (unsigned int)-1)
  945         err = -ENXIO;
  946     return err;
  947 }
  948 
  949 /**
  950  * \brief Write structured data from given buffer to an element set.
  951  * \param ctl A handle of backend module for control interface.
  952  * \param id ID of an element.
  953  * \param tlv An array with members of unsigned int type. The second member
  954  *        must represent total bytes of the rest of array.
  955  * \retval 0 on success
  956  * \retval >0 on success when value was changed
  957  * \retval <0 a negative error code
  958  *
  959  * The format of an array of \a tlv argument is:
  960  *   tlv[0]:   Type. One of SND_CTL_TLVT_XXX.
  961  *   tlv[1]:   Length. The length of value in units of byte.
  962  *   tlv[2..]: Value. Depending on the type.
  963  *
  964  * Details are described in <sound/tlv.h>.
  965  */
  966 int snd_ctl_elem_tlv_write(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  967                const unsigned int *tlv)
  968 {
  969     assert(ctl && id && (id->name[0] || id->numid) && tlv);
  970     return snd_ctl_tlv_do(ctl, 1, id, (unsigned int *)tlv,
  971             tlv[SNDRV_CTL_TLVO_LEN] + 2 * sizeof(unsigned int));
  972 }
  973 
  974 /**
  975  * \brief Process structured data from given buffer for an element set.
  976  * \param ctl A handle of backend module for control interface.
  977  * \param id ID of an element.
  978  * \param tlv An array with members of unsigned int type. The second member
  979  *        must represent total bytes of the rest of array.
  980  * \retval 0 on success
  981  * \retval >0 on success when value was changed
  982  * \retval <0 a negative error code
  983  *
  984  * The format of an array of \a tlv argument is:
  985  *   tlv[0]:   Type. One of SND_CTL_TLVT_XXX.
  986  *   tlv[1]:   Length. The length of value in units of byte.
  987  *   tlv[2..]: Value. Depending on the type.
  988  *
  989  * Details are described in <sound/tlv.h>.
  990  */
  991 int snd_ctl_elem_tlv_command(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id,
  992                  const unsigned int *tlv)
  993 {
  994     assert(ctl && id && (id->name[0] || id->numid) && tlv);
  995     return snd_ctl_tlv_do(ctl, -1, id, (unsigned int *)tlv,
  996             tlv[SNDRV_CTL_TLVO_LEN] + 2 * sizeof(unsigned int));
  997 }
  998 
  999 /**
 1000  * \brief Lock CTL element
 1001  * \param ctl CTL handle
 1002  * \param id CTL element id pointer
 1003  * \return 0 on success otherwise a negative error code
 1004  */
 1005 int snd_ctl_elem_lock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
 1006 {
 1007     assert(ctl && id);
 1008     return ctl->ops->element_lock(ctl, id);
 1009 }
 1010 
 1011 /**
 1012  * \brief Unlock CTL element
 1013  * \param ctl CTL handle
 1014  * \param id CTL element id pointer
 1015  * \return 0 on success otherwise a negative error code
 1016  */
 1017 int snd_ctl_elem_unlock(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
 1018 {
 1019     assert(ctl && id);
 1020     return ctl->ops->element_unlock(ctl, id);
 1021 }
 1022 
 1023 /**
 1024  * \brief Get next hardware dependent device number
 1025  * \param ctl CTL handle
 1026  * \param device current device on entry and next device on return
 1027  * \return 0 on success otherwise a negative error code
 1028  */
 1029 int snd_ctl_hwdep_next_device(snd_ctl_t *ctl, int *device)
 1030 {
 1031     assert(ctl && device);
 1032     return ctl->ops->hwdep_next_device(ctl, device);
 1033 }
 1034 
 1035 /**
 1036  * \brief Get info about a hardware dependent device
 1037  * \param ctl CTL handle
 1038  * \param info Hardware dependent device id/info pointer
 1039  * \return 0 on success otherwise a negative error code
 1040  */
 1041 int snd_ctl_hwdep_info(snd_ctl_t *ctl, snd_hwdep_info_t * info)
 1042 {
 1043     assert(ctl && info);
 1044     return ctl->ops->hwdep_info(ctl, info);
 1045 }
 1046 
 1047 /**
 1048  * \brief Get next PCM device number
 1049  * \param ctl CTL handle
 1050  * \param device current device on entry and next device on return
 1051  * \return 0 on success otherwise a negative error code
 1052  */
 1053 int snd_ctl_pcm_next_device(snd_ctl_t *ctl, int * device)
 1054 {
 1055     assert(ctl && device);
 1056     return ctl->ops->pcm_next_device(ctl, device);
 1057 }
 1058 
 1059 /**
 1060  * \brief Get info about a PCM device
 1061  * \param ctl CTL handle
 1062  * \param info PCM device id/info pointer
 1063  * \return 0 on success otherwise a negative error code
 1064  */
 1065 int snd_ctl_pcm_info(snd_ctl_t *ctl, snd_pcm_info_t * info)
 1066 {
 1067     assert(ctl && info);
 1068     return ctl->ops->pcm_info(ctl, info);
 1069 }
 1070 
 1071 /**
 1072  * \brief Set preferred PCM subdevice number of successive PCM open
 1073  * \param ctl CTL handle
 1074  * \param subdev Preferred PCM subdevice number
 1075  * \return 0 on success otherwise a negative error code
 1076  */
 1077 int snd_ctl_pcm_prefer_subdevice(snd_ctl_t *ctl, int subdev)
 1078 {
 1079     assert(ctl);
 1080     return ctl->ops->pcm_prefer_subdevice(ctl, subdev);
 1081 }
 1082 
 1083 /**
 1084  * \brief Get next RawMidi device number
 1085  * \param ctl CTL handle
 1086  * \param device current device on entry and next device on return
 1087  * \return 0 on success otherwise a negative error code
 1088  */
 1089 int snd_ctl_rawmidi_next_device(snd_ctl_t *ctl, int * device)
 1090 {
 1091     assert(ctl && device);
 1092     return ctl->ops->rawmidi_next_device(ctl, device);
 1093 }
 1094 
 1095 /**
 1096  * \brief Get info about a RawMidi device
 1097  * \param ctl CTL handle
 1098  * \param info RawMidi device id/info pointer
 1099  * \return 0 on success otherwise a negative error code
 1100  */
 1101 int snd_ctl_rawmidi_info(snd_ctl_t *ctl, snd_rawmidi_info_t * info)
 1102 {
 1103     assert(ctl && info);
 1104     return ctl->ops->rawmidi_info(ctl, info);
 1105 }
 1106 
 1107 /**
 1108  * \brief Set preferred RawMidi subdevice number of successive RawMidi open
 1109  * \param ctl CTL handle
 1110  * \param subdev Preferred RawMidi subdevice number
 1111  * \return 0 on success otherwise a negative error code
 1112  */
 1113 int snd_ctl_rawmidi_prefer_subdevice(snd_ctl_t *ctl, int subdev)
 1114 {
 1115     assert(ctl);
 1116     return ctl->ops->rawmidi_prefer_subdevice(ctl, subdev);
 1117 }
 1118 
 1119 /**
 1120  * \brief Set Power State to given SND_CTL_POWER_* value and do the power management
 1121  * \param ctl CTL handle
 1122  * \param state Desired Power State
 1123  * \return 0 on success otherwise a negative error code
 1124  */
 1125 int snd_ctl_set_power_state(snd_ctl_t *ctl, unsigned int state)
 1126 {
 1127     assert(ctl);
 1128     if (ctl->ops->set_power_state)
 1129         return ctl->ops->set_power_state(ctl, state);
 1130     return -ENXIO;
 1131 }
 1132 
 1133 /**
 1134  * \brief Get actual Power State
 1135  * \param ctl CTL handle
 1136  * \param state Destination value
 1137  * \return 0 on success otherwise a negative error code
 1138  */
 1139 int snd_ctl_get_power_state(snd_ctl_t *ctl, unsigned int *state)
 1140 {
 1141     assert(ctl);
 1142     if (ctl->ops->get_power_state)
 1143         return ctl->ops->get_power_state(ctl, state);
 1144     return -ENXIO;
 1145 }
 1146 
 1147 /**
 1148  * \brief Read an event
 1149  * \param ctl CTL handle
 1150  * \param event Event pointer
 1151  * \return number of events read otherwise a negative error code on failure
 1152  */
 1153 int snd_ctl_read(snd_ctl_t *ctl, snd_ctl_event_t *event)
 1154 {
 1155     assert(ctl && event);
 1156     return (ctl->ops->read)(ctl, event);
 1157 }
 1158 
 1159 /**
 1160  * \brief Wait for a CTL to become ready (i.e. at least one event pending)
 1161  * \param ctl CTL handle
 1162  * \param timeout maximum time in milliseconds to wait
 1163  * \return 0 otherwise a negative error code on failure
 1164  */
 1165 int snd_ctl_wait(snd_ctl_t *ctl, int timeout)
 1166 {
 1167     struct pollfd *pfd;
 1168     unsigned short revents;
 1169     int npfds, err, err_poll;
 1170 
 1171     npfds = snd_ctl_poll_descriptors_count(ctl);
 1172     if (npfds <= 0 || npfds >= 16) {
 1173         SNDERR("Invalid poll_fds %d\n", npfds);
 1174         return -EIO;
 1175     }
 1176     pfd = alloca(sizeof(*pfd) * npfds);
 1177     err = snd_ctl_poll_descriptors(ctl, pfd, npfds);
 1178     if (err < 0)
 1179         return err;
 1180     if (err != npfds) {
 1181         SNDMSG("invalid poll descriptors %d\n", err);
 1182         return -EIO;
 1183     }
 1184     for (;;) {
 1185         err_poll = poll(pfd, npfds, timeout);
 1186         if (err_poll < 0)
 1187             return -errno;
 1188         if (! err_poll)
 1189             return 0;
 1190         err = snd_ctl_poll_descriptors_revents(ctl, pfd, npfds, &revents);
 1191         if (err < 0)
 1192             return err;
 1193         if (revents & (POLLERR | POLLNVAL))
 1194             return -EIO;
 1195         if (revents & (POLLIN | POLLOUT))
 1196             return 1;
 1197     }
 1198 }
 1199 
 1200 /**
 1201  * \brief Add an async handler for a CTL
 1202  * \param handler Returned handler handle
 1203  * \param ctl CTL handle
 1204  * \param callback Callback function
 1205  * \param private_data Callback private data
 1206  * \return 0 otherwise a negative error code on failure
 1207  */
 1208 int snd_async_add_ctl_handler(snd_async_handler_t **handler, snd_ctl_t *ctl, 
 1209                   snd_async_callback_t callback, void *private_data)
 1210 {
 1211     int err;
 1212     int was_empty;
 1213     snd_async_handler_t *h;
 1214     err = snd_async_add_handler(&h, _snd_ctl_async_descriptor(ctl),
 1215                     callback, private_data);
 1216     if (err < 0)
 1217         return err;
 1218     h->type = SND_ASYNC_HANDLER_CTL;
 1219     h->u.ctl = ctl;
 1220     was_empty = list_empty(&ctl->async_handlers);
 1221     list_add_tail(&h->hlist, &ctl->async_handlers);
 1222     if (was_empty) {
 1223         err = snd_ctl_async(ctl, snd_async_handler_get_signo(h), getpid());
 1224         if (err < 0) {
 1225             snd_async_del_handler(h);
 1226             return err;
 1227         }
 1228     }
 1229     *handler = h;
 1230     return 0;
 1231 }
 1232 
 1233 /**
 1234  * \brief Return CTL handle related to an async handler
 1235  * \param handler Async handler handle
 1236  * \return CTL handle
 1237  */
 1238 snd_ctl_t *snd_async_handler_get_ctl(snd_async_handler_t *handler)
 1239 {
 1240     assert(handler->type == SND_ASYNC_HANDLER_CTL);
 1241     return handler->u.ctl;
 1242 }
 1243 
 1244 static const char *const build_in_ctls[] = {
 1245     "hw", "shm", NULL
 1246 };
 1247 
 1248 static int snd_ctl_open_conf(snd_ctl_t **ctlp, const char *name,
 1249                  snd_config_t *ctl_root, snd_config_t *ctl_conf, int mode)
 1250 {
 1251     const char *str;
 1252     char *buf = NULL, *buf1 = NULL;
 1253     int err;
 1254     snd_config_t *conf, *type_conf = NULL;
 1255     snd_config_iterator_t i, next;
 1256     const char *lib = NULL, *open_name = NULL;
 1257     const char *id;
 1258     int (*open_func)(snd_ctl_t **, const char *, snd_config_t *, snd_config_t *, int) = NULL;
 1259 #ifndef PIC
 1260     extern void *snd_control_open_symbols(void);
 1261 #endif
 1262     if (snd_config_get_type(ctl_conf) != SND_CONFIG_TYPE_COMPOUND) {
 1263         if (name)
 1264             SNDERR("Invalid type for CTL %s definition", name);
 1265         else
 1266             SNDERR("Invalid type for CTL definition");
 1267         return -EINVAL;
 1268     }
 1269     err = snd_config_search(ctl_conf, "type", &conf);
 1270     if (err < 0) {
 1271         SNDERR("type is not defined");
 1272         return err;
 1273     }
 1274     err = snd_config_get_id(conf, &id);
 1275     if (err < 0) {
 1276         SNDERR("unable to get id");
 1277         return err;
 1278     }
 1279     err = snd_config_get_string(conf, &str);
 1280     if (err < 0) {
 1281         SNDERR("Invalid type for %s", id);
 1282         return err;
 1283     }
 1284     err = snd_config_search_definition(ctl_root, "ctl_type", str, &type_conf);
 1285     if (err >= 0) {
 1286         if (snd_config_get_type(type_conf) != SND_CONFIG_TYPE_COMPOUND) {
 1287             SNDERR("Invalid type for CTL type %s definition", str);
 1288             err = -EINVAL;
 1289             goto _err;
 1290         }
 1291         snd_config_for_each(i, next, type_conf) {
 1292             snd_config_t *n = snd_config_iterator_entry(i);
 1293             const char *id;
 1294             if (snd_config_get_id(n, &id) < 0)
 1295                 continue;
 1296             if (strcmp(id, "comment") == 0)
 1297                 continue;
 1298             if (strcmp(id, "lib") == 0) {
 1299                 err = snd_config_get_string(n, &lib);
 1300                 if (err < 0) {
 1301                     SNDERR("Invalid type for %s", id);
 1302                     goto _err;
 1303                 }
 1304                 continue;
 1305             }
 1306             if (strcmp(id, "open") == 0) {
 1307                 err = snd_config_get_string(n, &open_name);
 1308                 if (err < 0) {
 1309                     SNDERR("Invalid type for %s", id);
 1310                     goto _err;
 1311                 }
 1312                 continue;
 1313             }
 1314             SNDERR("Unknown field %s", id);
 1315             err = -EINVAL;
 1316             goto _err;
 1317         }
 1318     }
 1319     if (!open_name) {
 1320         buf = malloc(strlen(str) + 32);
 1321         if (buf == NULL) {
 1322             err = -ENOMEM;
 1323             goto _err;
 1324         }
 1325         open_name = buf;
 1326         sprintf(buf, "_snd_ctl_%s_open", str);
 1327     }
 1328     if (!lib) {
 1329         const char *const *build_in = build_in_ctls;
 1330         while (*build_in) {
 1331             if (!strcmp(*build_in, str))
 1332                 break;
 1333             build_in++;
 1334         }
 1335         if (*build_in == NULL) {
 1336             buf1 = malloc(strlen(str) + sizeof(ALSA_PLUGIN_DIR) + 32);
 1337             if (buf1 == NULL) {
 1338                 err = -ENOMEM;
 1339                 goto _err;
 1340             }
 1341             lib = buf1;
 1342             sprintf(buf1, "%s/libasound_module_ctl_%s.so", ALSA_PLUGIN_DIR, str);
 1343         }
 1344     }
 1345 #ifndef PIC
 1346     snd_control_open_symbols();
 1347 #endif
 1348     open_func = snd_dlobj_cache_get(lib, open_name,
 1349             SND_DLSYM_VERSION(SND_CONTROL_DLSYM_VERSION), 1);
 1350     if (open_func) {
 1351         err = open_func(ctlp, name, ctl_root, ctl_conf, mode);
 1352         if (err >= 0) {
 1353             (*ctlp)->open_func = open_func;
 1354             err = 0;
 1355         } else {
 1356             snd_dlobj_cache_put(open_func);
 1357         }
 1358     } else {
 1359         err = -ENXIO;
 1360     }
 1361        _err:
 1362     if (type_conf)
 1363         snd_config_delete(type_conf);
 1364     free(buf);
 1365     free(buf1);
 1366     return err;
 1367 }
 1368 
 1369 static int snd_ctl_open_noupdate(snd_ctl_t **ctlp, snd_config_t *root, const char *name, int mode)
 1370 {
 1371     int err;
 1372     snd_config_t *ctl_conf;
 1373     err = snd_config_search_definition(root, "ctl", name, &ctl_conf);
 1374     if (err < 0) {
 1375         SNDERR("Invalid CTL %s", name);
 1376         return err;
 1377     }
 1378     err = snd_ctl_open_conf(ctlp, name, root, ctl_conf, mode);
 1379     snd_config_delete(ctl_conf);
 1380     return err;
 1381 }
 1382 
 1383 /**
 1384  * \brief Opens a CTL
 1385  * \param ctlp Returned CTL handle
 1386  * \param name ASCII identifier of the CTL handle
 1387  * \param mode Open mode (see #SND_CTL_NONBLOCK, #SND_CTL_ASYNC)
 1388  * \return 0 on success otherwise a negative error code
 1389  */
 1390 int snd_ctl_open(snd_ctl_t **ctlp, const char *name, int mode)
 1391 {
 1392     snd_config_t *top;
 1393     int err;
 1394 
 1395     assert(ctlp && name);
 1396     err = snd_config_update_ref(&top);
 1397     if (err < 0)
 1398         return err;
 1399     err = snd_ctl_open_noupdate(ctlp, top, name, mode);
 1400     snd_config_unref(top);
 1401     return err;
 1402 }
 1403 
 1404 /**
 1405  * \brief Opens a CTL using local configuration
 1406  * \param ctlp Returned CTL handle
 1407  * \param name ASCII identifier of the CTL handle
 1408  * \param mode Open mode (see #SND_CTL_NONBLOCK, #SND_CTL_ASYNC)
 1409  * \param lconf Local configuration
 1410  * \return 0 on success otherwise a negative error code
 1411  */
 1412 int snd_ctl_open_lconf(snd_ctl_t **ctlp, const char *name,
 1413                int mode, snd_config_t *lconf)
 1414 {
 1415     assert(ctlp && name && lconf);
 1416     return snd_ctl_open_noupdate(ctlp, lconf, name, mode);
 1417 }
 1418 
 1419 /**
 1420  * \brief Opens a fallback CTL
 1421  * \param ctlp Returned CTL handle
 1422  * \param root Configuration root
 1423  * \param name ASCII identifier of the CTL handle used as fallback
 1424  * \param orig_name The original ASCII name
 1425  * \param mode Open mode (see #SND_CTL_NONBLOCK, #SND_CTL_ASYNC)
 1426  * \return 0 on success otherwise a negative error code
 1427  */
 1428 int snd_ctl_open_fallback(snd_ctl_t **ctlp, snd_config_t *root,
 1429               const char *name, const char *orig_name, int mode)
 1430 {
 1431     int err;
 1432     assert(ctlp && name && root);
 1433     err = snd_ctl_open_noupdate(ctlp, root, name, mode);
 1434     if (err >= 0) {
 1435         free((*ctlp)->name);
 1436         (*ctlp)->name = orig_name ? strdup(orig_name) : NULL;
 1437     }
 1438     return err;
 1439 }
 1440 
 1441 #ifndef DOC_HIDDEN
 1442 #define TYPE(v) [SND_CTL_ELEM_TYPE_##v] = #v
 1443 #define IFACE(v) [SND_CTL_ELEM_IFACE_##v] = #v
 1444 #define IFACE1(v, n) [SND_CTL_ELEM_IFACE_##v] = #n
 1445 #define EVENT(v) [SND_CTL_EVENT_##v] = #v
 1446 
 1447 static const char *const snd_ctl_elem_type_names[] = {
 1448     TYPE(NONE),
 1449     TYPE(BOOLEAN),
 1450     TYPE(INTEGER),
 1451     TYPE(ENUMERATED),
 1452     TYPE(BYTES),
 1453     TYPE(IEC958),
 1454     TYPE(INTEGER64),
 1455 };
 1456 
 1457 static const char *const snd_ctl_elem_iface_names[] = {
 1458     IFACE(CARD),
 1459     IFACE(HWDEP),
 1460     IFACE(MIXER),
 1461     IFACE(PCM),
 1462     IFACE(RAWMIDI),
 1463     IFACE(TIMER),
 1464     IFACE(SEQUENCER),
 1465 };
 1466 
 1467 static const char *const snd_ctl_event_type_names[] = {
 1468     EVENT(ELEM),
 1469 };
 1470 #endif
 1471 
 1472 /**
 1473  * \brief get name of a CTL element type
 1474  * \param type CTL element type
 1475  * \return ascii name of CTL element type
 1476  */
 1477 const char *snd_ctl_elem_type_name(snd_ctl_elem_type_t type)
 1478 {
 1479     assert(type <= SND_CTL_ELEM_TYPE_LAST);
 1480     return snd_ctl_elem_type_names[type];
 1481 }
 1482 
 1483 /**
 1484  * \brief get name of a CTL element related interface
 1485  * \param iface CTL element related interface
 1486  * \return ascii name of CTL element related interface
 1487  */
 1488 const char *snd_ctl_elem_iface_name(snd_ctl_elem_iface_t iface)
 1489 {
 1490     assert(iface <= SND_CTL_ELEM_IFACE_LAST);
 1491     return snd_ctl_elem_iface_names[iface];
 1492 }
 1493 
 1494 /**
 1495  * \brief get name of a CTL event type
 1496  * \param type CTL event type
 1497  * \return ascii name of CTL event type
 1498  */
 1499 const char *snd_ctl_event_type_name(snd_ctl_event_type_t type)
 1500 {
 1501     assert(type <= SND_CTL_EVENT_LAST);
 1502     return snd_ctl_event_type_names[type];
 1503 }
 1504 
 1505 /**
 1506  * \brief allocate space for CTL element identifiers list
 1507  * \param obj CTL element identifiers list
 1508  * \param entries Entries to allocate
 1509  * \return 0 on success otherwise a negative error code
 1510  */
 1511 int snd_ctl_elem_list_alloc_space(snd_ctl_elem_list_t *obj, unsigned int entries)
 1512 {
 1513     free(obj->pids);
 1514     obj->pids = calloc(entries, sizeof(*obj->pids));
 1515     if (!obj->pids) {
 1516         obj->space = 0;
 1517         return -ENOMEM;
 1518     }
 1519     obj->space = entries;
 1520     return 0;
 1521 }  
 1522 
 1523 /**
 1524  * \brief free previously allocated space for CTL element identifiers list
 1525  * \param obj CTL element identifiers list
 1526  */
 1527 void snd_ctl_elem_list_free_space(snd_ctl_elem_list_t *obj)
 1528 {
 1529     free(obj->pids);
 1530     obj->pids = NULL;
 1531     obj->space = 0;
 1532 }
 1533 
 1534 /**
 1535  * \brief Get event mask for an element related event
 1536  * \param obj CTL event
 1537  * \return event mask for element related event
 1538  */
 1539 unsigned int snd_ctl_event_elem_get_mask(const snd_ctl_event_t *obj)
 1540 {
 1541     assert(obj);
 1542     assert(obj->type == SND_CTL_EVENT_ELEM);
 1543     return obj->data.elem.mask;
 1544 }
 1545 
 1546 /**
 1547  * \brief Get CTL element identifier for an element related event
 1548  * \param obj CTL event
 1549  * \param ptr Pointer to returned CTL element identifier
 1550  */
 1551 void snd_ctl_event_elem_get_id(const snd_ctl_event_t *obj, snd_ctl_elem_id_t *ptr)
 1552 {
 1553     assert(obj && ptr);
 1554     assert(obj->type == SND_CTL_EVENT_ELEM);
 1555     *ptr = obj->data.elem.id;
 1556 }
 1557 
 1558 /**
 1559  * \brief Get element numeric identifier for an element related event
 1560  * \param obj CTL event
 1561  * \return element numeric identifier
 1562  */
 1563 unsigned int snd_ctl_event_elem_get_numid(const snd_ctl_event_t *obj)
 1564 {
 1565     assert(obj);
 1566     assert(obj->type == SND_CTL_EVENT_ELEM);
 1567     return obj->data.elem.id.numid;
 1568 }
 1569 
 1570 /**
 1571  * \brief Get interface part of CTL element identifier for an element related event
 1572  * \param obj CTL event
 1573  * \return interface part of element identifier
 1574  */
 1575 snd_ctl_elem_iface_t snd_ctl_event_elem_get_interface(const snd_ctl_event_t *obj)
 1576 {
 1577     assert(obj);
 1578     assert(obj->type == SND_CTL_EVENT_ELEM);
 1579     return obj->data.elem.id.iface;
 1580 }
 1581 
 1582 /**
 1583  * \brief Get device part of CTL element identifier for an element related event
 1584  * \param obj CTL event
 1585  * \return device part of element identifier
 1586  */
 1587 unsigned int snd_ctl_event_elem_get_device(const snd_ctl_event_t *obj)
 1588 {
 1589     assert(obj);
 1590     assert(obj->type == SND_CTL_EVENT_ELEM);
 1591     return obj->data.elem.id.device;
 1592 }
 1593 
 1594 /**
 1595  * \brief Get subdevice part of CTL element identifier for an element related event
 1596  * \param obj CTL event
 1597  * \return subdevice part of element identifier
 1598  */
 1599 unsigned int snd_ctl_event_elem_get_subdevice(const snd_ctl_event_t *obj)
 1600 {
 1601     assert(obj);
 1602     assert(obj->type == SND_CTL_EVENT_ELEM);
 1603     return obj->data.elem.id.subdevice;
 1604 }
 1605 
 1606 /**
 1607  * \brief Get name part of CTL element identifier for an element related event
 1608  * \param obj CTL event
 1609  * \return name part of element identifier
 1610  */
 1611 const char *snd_ctl_event_elem_get_name(const snd_ctl_event_t *obj)
 1612 {
 1613     assert(obj);
 1614     assert(obj->type == SND_CTL_EVENT_ELEM);
 1615     return (const char *)obj->data.elem.id.name;
 1616 }
 1617 
 1618 /**
 1619  * \brief Get index part of CTL element identifier for an element related event
 1620  * \param obj CTL event
 1621  * \return index part of element identifier
 1622  */
 1623 unsigned int snd_ctl_event_elem_get_index(const snd_ctl_event_t *obj)
 1624 {
 1625     assert(obj);
 1626     assert(obj->type == SND_CTL_EVENT_ELEM);
 1627     return obj->data.elem.id.index;
 1628 }
 1629 
 1630 #ifndef DOC_HIDDEN
 1631 int _snd_ctl_poll_descriptor(snd_ctl_t *ctl)
 1632 {
 1633     assert(ctl);
 1634     return ctl->poll_fd;
 1635 }
 1636 #endif
 1637 
 1638 /**
 1639  * \brief get size of #snd_ctl_elem_id_t
 1640  * \return size in bytes
 1641  */
 1642 size_t snd_ctl_elem_id_sizeof()
 1643 {
 1644     return sizeof(snd_ctl_elem_id_t);
 1645 }
 1646 
 1647 /**
 1648  * \brief allocate an invalid #snd_ctl_elem_id_t using standard malloc
 1649  * \param ptr returned pointer
 1650  * \return 0 on success otherwise negative error code
 1651  */
 1652 int snd_ctl_elem_id_malloc(snd_ctl_elem_id_t **ptr)
 1653 {
 1654     assert(ptr);
 1655     *ptr = calloc(1, sizeof(snd_ctl_elem_id_t));
 1656     if (!*ptr)
 1657         return -ENOMEM;
 1658     return 0;
 1659 }
 1660 
 1661 /**
 1662  * \brief frees a previously allocated #snd_ctl_elem_id_t
 1663  * \param obj pointer to object to free
 1664  */
 1665 void snd_ctl_elem_id_free(snd_ctl_elem_id_t *obj)
 1666 {
 1667     free(obj);
 1668 }
 1669 
 1670 /**
 1671  * \brief clear given #snd_ctl_elem_id_t object
 1672  * \param obj pointer to object to clear
 1673  */
 1674 void snd_ctl_elem_id_clear(snd_ctl_elem_id_t *obj)
 1675 {
 1676     memset(obj, 0, sizeof(snd_ctl_elem_id_t));
 1677 }
 1678 
 1679 /**
 1680  * \brief copy one #snd_ctl_elem_id_t to another
 1681  * \param dst pointer to destination
 1682  * \param src pointer to source
 1683  */
 1684 void snd_ctl_elem_id_copy(snd_ctl_elem_id_t *dst, const snd_ctl_elem_id_t *src)
 1685 {
 1686     assert(dst && src);
 1687     *dst = *src;
 1688 }
 1689 
 1690 /**
 1691  * \brief Get numeric identifier from a CTL element identifier
 1692  * \param obj CTL element identifier
 1693  * \return CTL element numeric identifier
 1694  */
 1695 unsigned int snd_ctl_elem_id_get_numid(const snd_ctl_elem_id_t *obj)
 1696 {
 1697     assert(obj);
 1698     return obj->numid;
 1699 }
 1700 
 1701 /**
 1702  * \brief Get interface part of a CTL element identifier
 1703  * \param obj CTL element identifier
 1704  * \return CTL element related interface
 1705  */
 1706 snd_ctl_elem_iface_t snd_ctl_elem_id_get_interface(const snd_ctl_elem_id_t *obj)
 1707 {
 1708     assert(obj);
 1709     return obj->iface;
 1710 }
 1711 
 1712 /**
 1713  * \brief Get device part of a CTL element identifier
 1714  * \param obj CTL element identifier
 1715  * \return CTL element related device
 1716  */
 1717 unsigned int snd_ctl_elem_id_get_device(const snd_ctl_elem_id_t *obj)
 1718 {
 1719     assert(obj);
 1720     return obj->device;
 1721 }
 1722 
 1723 /**
 1724  * \brief Get subdevice part of a CTL element identifier
 1725  * \param obj CTL element identifier
 1726  * \return CTL element related subdevice
 1727  */
 1728 unsigned int snd_ctl_elem_id_get_subdevice(const snd_ctl_elem_id_t *obj)
 1729 {
 1730     assert(obj);
 1731     return obj->subdevice;
 1732 }
 1733 
 1734 /**
 1735  * \brief Get name part of a CTL element identifier
 1736  * \param obj CTL element identifier
 1737  * \return CTL element name
 1738  */
 1739 const char *snd_ctl_elem_id_get_name(const snd_ctl_elem_id_t *obj)
 1740 {
 1741     assert(obj);
 1742     return (const char *)obj->name;
 1743 }
 1744 
 1745 /**
 1746  * \brief Get index part of a CTL element identifier
 1747  * \param obj CTL element identifier
 1748  * \return CTL element index
 1749  */
 1750 unsigned int snd_ctl_elem_id_get_index(const snd_ctl_elem_id_t *obj)
 1751 {
 1752     assert(obj);
 1753     return obj->index;
 1754 }
 1755 
 1756 /**
 1757  * \brief Set numeric identifier for a CTL element identifier
 1758  * \param obj CTL element identifier
 1759  * \param val CTL element numeric identifier
 1760  */
 1761 void snd_ctl_elem_id_set_numid(snd_ctl_elem_id_t *obj, unsigned int val)
 1762 {
 1763     assert(obj);
 1764     obj->numid = val;
 1765 }
 1766 
 1767 /**
 1768  * \brief Set interface part for a CTL element identifier
 1769  * \param obj CTL element identifier
 1770  * \param val CTL element related interface
 1771  */
 1772 void snd_ctl_elem_id_set_interface(snd_ctl_elem_id_t *obj, snd_ctl_elem_iface_t val)
 1773 {
 1774     assert(obj);
 1775     obj->iface = val;
 1776 }
 1777 
 1778 /**
 1779  * \brief Set device part for a CTL element identifier
 1780  * \param obj CTL element identifier
 1781  * \param val CTL element related device
 1782  */
 1783 void snd_ctl_elem_id_set_device(snd_ctl_elem_id_t *obj, unsigned int val)
 1784 {
 1785     assert(obj);
 1786     obj->device = val;
 1787 }
 1788 
 1789 /**
 1790  * \brief Set subdevice part for a CTL element identifier
 1791  * \param obj CTL element identifier
 1792  * \param val CTL element related subdevice
 1793  */
 1794 void snd_ctl_elem_id_set_subdevice(snd_ctl_elem_id_t *obj, unsigned int val)
 1795 {
 1796     assert(obj);
 1797     obj->subdevice = val;
 1798 }
 1799 
 1800 /**
 1801  * \brief Set name part for a CTL element identifier
 1802  * \param obj CTL element identifier
 1803  * \param val CTL element name
 1804  */
 1805 void snd_ctl_elem_id_set_name(snd_ctl_elem_id_t *obj, const char *val)
 1806 {
 1807     assert(obj);
 1808     snd_strlcpy((char *)obj->name, val, sizeof(obj->name));
 1809 }
 1810 
 1811 /**
 1812  * \brief Set index part for a CTL element identifier
 1813  * \param obj CTL element identifier
 1814  * \param val CTL element index
 1815  */
 1816 void snd_ctl_elem_id_set_index(snd_ctl_elem_id_t *obj, unsigned int val)
 1817 {
 1818     assert(obj);
 1819     obj->index = val;
 1820 }
 1821 
 1822 /**
 1823  * \brief get size of #snd_ctl_card_info_t
 1824  * \return size in bytes
 1825  */
 1826 size_t snd_ctl_card_info_sizeof()
 1827 {
 1828     return sizeof(snd_ctl_card_info_t);
 1829 }
 1830 
 1831 /**
 1832  * \brief allocate an invalid #snd_ctl_card_info_t using standard malloc
 1833  * \param ptr returned pointer
 1834  * \return 0 on success otherwise negative error code
 1835  */
 1836 int snd_ctl_card_info_malloc(snd_ctl_card_info_t **ptr)
 1837 {
 1838     assert(ptr);
 1839     *ptr = calloc(1, sizeof(snd_ctl_card_info_t));
 1840     if (!*ptr)
 1841         return -ENOMEM;
 1842     return 0;
 1843 }
 1844 
 1845 /**
 1846  * \brief frees a previously allocated #snd_ctl_card_info_t
 1847  * \param obj pointer to object to free
 1848  */
 1849 void snd_ctl_card_info_free(snd_ctl_card_info_t *obj)
 1850 {
 1851     free(obj);
 1852 }
 1853 
 1854 /**
 1855  * \brief clear given #snd_ctl_card_info_t object
 1856  * \param obj pointer to object to clear
 1857  */
 1858 void snd_ctl_card_info_clear(snd_ctl_card_info_t *obj)
 1859 {
 1860     memset(obj, 0, sizeof(snd_ctl_card_info_t));
 1861 }
 1862 
 1863 /**
 1864  * \brief copy one #snd_ctl_card_info_t to another
 1865  * \param dst pointer to destination
 1866  * \param src pointer to source
 1867  */
 1868 void snd_ctl_card_info_copy(snd_ctl_card_info_t *dst, const snd_ctl_card_info_t *src)
 1869 {
 1870     assert(dst && src);
 1871     *dst = *src;
 1872 }
 1873 
 1874 /**
 1875  * \brief Get card number from a CTL card info
 1876  * \param obj CTL card info
 1877  * \return card number
 1878  */
 1879 int snd_ctl_card_info_get_card(const snd_ctl_card_info_t *obj)
 1880 {
 1881     assert(obj);
 1882     return obj->card;
 1883 }
 1884 
 1885 /**
 1886  * \brief Get card identifier from a CTL card info
 1887  * \param obj CTL card info
 1888  * \return card identifier
 1889  */
 1890 const char *snd_ctl_card_info_get_id(const snd_ctl_card_info_t *obj)
 1891 {
 1892     assert(obj);
 1893     return (const char *)obj->id;
 1894 }
 1895 
 1896 /**
 1897  * \brief Get card driver name from a CTL card info
 1898  * \param obj CTL card info
 1899  * \return card driver name
 1900  */
 1901 const char *snd_ctl_card_info_get_driver(const snd_ctl_card_info_t *obj)
 1902 {
 1903     assert(obj);
 1904     return (const char *)obj->driver;
 1905 }
 1906 
 1907 /**
 1908  * \brief Get card name from a CTL card info
 1909  * \param obj CTL card info
 1910  * \return card name
 1911  */
 1912 const char *snd_ctl_card_info_get_name(const snd_ctl_card_info_t *obj)
 1913 {
 1914     assert(obj);
 1915     return (const char *)obj->name;
 1916 }
 1917 
 1918 /**
 1919  * \brief Get card long name from a CTL card info
 1920  * \param obj CTL card info
 1921  * \return card long name
 1922  */
 1923 const char *snd_ctl_card_info_get_longname(const snd_ctl_card_info_t *obj)
 1924 {
 1925     assert(obj);
 1926     return (const char *)obj->longname;
 1927 }
 1928 
 1929 /**
 1930  * \brief Get card mixer name from a CTL card info
 1931  * \param obj CTL card info
 1932  * \return card mixer name
 1933  */
 1934 const char *snd_ctl_card_info_get_mixername(const snd_ctl_card_info_t *obj)
 1935 {
 1936     assert(obj);
 1937     return (const char *)obj->mixername;
 1938 }
 1939 
 1940 /**
 1941  * \brief Get card component list from a CTL card info
 1942  * \param obj CTL card info
 1943  * \return card mixer identifier
 1944  */
 1945 const char *snd_ctl_card_info_get_components(const snd_ctl_card_info_t *obj)
 1946 {
 1947     assert(obj);
 1948     return (const char *)obj->components;
 1949 }
 1950 
 1951 /**
 1952  * \brief get size of #snd_ctl_event_t
 1953  * \return size in bytes
 1954  */
 1955 size_t snd_ctl_event_sizeof()
 1956 {
 1957     return sizeof(snd_ctl_event_t);
 1958 }
 1959 
 1960 /**
 1961  * \brief allocate an invalid #snd_ctl_event_t using standard malloc
 1962  * \param ptr returned pointer
 1963  * \return 0 on success otherwise negative error code
 1964  */
 1965 int snd_ctl_event_malloc(snd_ctl_event_t **ptr)
 1966 {
 1967     assert(ptr);
 1968     *ptr = calloc(1, sizeof(snd_ctl_event_t));
 1969     if (!*ptr)
 1970         return -ENOMEM;
 1971     return 0;
 1972 }
 1973 
 1974 /**
 1975  * \brief frees a previously allocated #snd_ctl_event_t
 1976  * \param obj pointer to object to free
 1977  */
 1978 void snd_ctl_event_free(snd_ctl_event_t *obj)
 1979 {
 1980     free(obj);
 1981 }
 1982 
 1983 /**
 1984  * \brief clear given #snd_ctl_event_t object
 1985  * \param obj pointer to object to clear
 1986  */
 1987 void snd_ctl_event_clear(snd_ctl_event_t *obj)
 1988 {
 1989     memset(obj, 0, sizeof(snd_ctl_event_t));
 1990 }
 1991 
 1992 /**
 1993  * \brief copy one #snd_ctl_event_t to another
 1994  * \param dst pointer to destination
 1995  * \param src pointer to source
 1996  */
 1997 void snd_ctl_event_copy(snd_ctl_event_t *dst, const snd_ctl_event_t *src)
 1998 {
 1999     assert(dst && src);
 2000     *dst = *src;
 2001 }
 2002 
 2003 /**
 2004  * \brief Get type of a CTL event
 2005  * \param obj CTL event
 2006  * \return CTL event type
 2007  */
 2008 snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj)
 2009 {
 2010     assert(obj);
 2011     return obj->type;
 2012 }
 2013 
 2014 /**
 2015  * \brief get size of #snd_ctl_elem_list_t
 2016  * \return size in bytes
 2017  */
 2018 size_t snd_ctl_elem_list_sizeof()
 2019 {
 2020     return sizeof(snd_ctl_elem_list_t);
 2021 }
 2022 
 2023 /**
 2024  * \brief allocate an invalid #snd_ctl_elem_list_t using standard malloc
 2025  * \param ptr returned pointer
 2026  * \return 0 on success otherwise negative error code
 2027  */
 2028 int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr)
 2029 {
 2030     assert(ptr);
 2031     *ptr = calloc(1, sizeof(snd_ctl_elem_list_t));
 2032     if (!*ptr)
 2033         return -ENOMEM;
 2034     return 0;
 2035 }
 2036 
 2037 /**
 2038  * \brief frees a previously allocated #snd_ctl_elem_list_t
 2039  * \param obj pointer to object to free
 2040  */
 2041 void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj)
 2042 {
 2043     free(obj);
 2044 }
 2045 
 2046 /**
 2047  * \brief clear given #snd_ctl_elem_list_t object
 2048  * \param obj pointer to object to clear
 2049  */
 2050 void snd_ctl_elem_list_clear(snd_ctl_elem_list_t *obj)
 2051 {
 2052     memset(obj, 0, sizeof(snd_ctl_elem_list_t));
 2053 }
 2054 
 2055 /**
 2056  * \brief copy one #snd_ctl_elem_list_t to another
 2057  * \param dst pointer to destination
 2058  * \param src pointer to source
 2059  */
 2060 void snd_ctl_elem_list_copy(snd_ctl_elem_list_t *dst, const snd_ctl_elem_list_t *src)
 2061 {
 2062     assert(dst && src);
 2063     *dst = *src;
 2064 }
 2065 
 2066 /**
 2067  * \brief Set index of first wanted CTL element identifier in a CTL element identifiers list
 2068  * \param obj CTL element identifiers list
 2069  * \param val index of CTL element to put at position 0 of list
 2070  */
 2071 void snd_ctl_elem_list_set_offset(snd_ctl_elem_list_t *obj, unsigned int val)
 2072 {
 2073     assert(obj);
 2074     obj->offset = val;
 2075 }
 2076 
 2077 /**
 2078  * \brief Get number of used entries in CTL element identifiers list
 2079  * \param obj CTL element identifier list
 2080  * \return number of used entries
 2081  */
 2082 unsigned int snd_ctl_elem_list_get_used(const snd_ctl_elem_list_t *obj)
 2083 {
 2084     assert(obj);
 2085     return obj->used;
 2086 }
 2087 
 2088 /**
 2089  * \brief Get total count of elements present in CTL device (information present in every filled CTL element identifiers list)
 2090  * \param obj CTL element identifier list
 2091  * \return total number of elements
 2092  */
 2093 unsigned int snd_ctl_elem_list_get_count(const snd_ctl_elem_list_t *obj)
 2094 {
 2095     assert(obj);
 2096     return obj->count;
 2097 }
 2098 
 2099 /**
 2100  * \brief Get CTL element identifier for an entry of a CTL element identifiers list
 2101  * \param obj CTL element identifier list
 2102  * \param idx Index of entry
 2103  * \param ptr Pointer to returned CTL element identifier
 2104  */
 2105 void snd_ctl_elem_list_get_id(const snd_ctl_elem_list_t *obj, unsigned int idx, snd_ctl_elem_id_t *ptr)
 2106 {
 2107     assert(obj && ptr);
 2108     assert(idx < obj->used);
 2109     *ptr = obj->pids[idx];
 2110 }
 2111 
 2112 /**
 2113  * \brief Get CTL element numeric identifier for an entry of a CTL element identifiers list
 2114  * \param obj CTL element identifier list
 2115  * \param idx Index of entry
 2116  * \return CTL element numeric identifier
 2117  */
 2118 unsigned int snd_ctl_elem_list_get_numid(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2119 {
 2120     assert(obj);
 2121     assert(idx < obj->used);
 2122     return obj->pids[idx].numid;
 2123 }
 2124 
 2125 /**
 2126  * \brief Get interface part of CTL element identifier for an entry of a CTL element identifiers list
 2127  * \param obj CTL element identifier list
 2128  * \param idx Index of entry
 2129  * \return CTL element related interface
 2130  */
 2131 snd_ctl_elem_iface_t snd_ctl_elem_list_get_interface(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2132 {
 2133     assert(obj);
 2134     assert(idx < obj->used);
 2135     return obj->pids[idx].iface;
 2136 }
 2137 
 2138 /**
 2139  * \brief Get device part of CTL element identifier for an entry of a CTL element identifiers list
 2140  * \param obj CTL element identifier list
 2141  * \param idx Index of entry
 2142  * \return CTL element related device
 2143  */
 2144 unsigned int snd_ctl_elem_list_get_device(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2145 {
 2146     assert(obj);
 2147     assert(idx < obj->used);
 2148     return obj->pids[idx].device;
 2149 }
 2150 
 2151 /**
 2152  * \brief Get subdevice part of CTL element identifier for an entry of a CTL element identifiers list
 2153  * \param obj CTL element identifier list
 2154  * \param idx Index of entry
 2155  * \return CTL element related subdevice
 2156  */
 2157 unsigned int snd_ctl_elem_list_get_subdevice(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2158 {
 2159     assert(obj);
 2160     assert(idx < obj->used);
 2161     return obj->pids[idx].subdevice;
 2162 }
 2163 
 2164 /**
 2165  * \brief Get name part of CTL element identifier for an entry of a CTL element identifiers list
 2166  * \param obj CTL element identifier list
 2167  * \param idx Index of entry
 2168  * \return CTL element name
 2169  */
 2170 const char *snd_ctl_elem_list_get_name(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2171 {
 2172     assert(obj);
 2173     assert(idx < obj->used);
 2174     return (const char *)obj->pids[idx].name;
 2175 }
 2176 
 2177 /**
 2178  * \brief Get index part of CTL element identifier for an entry of a CTL element identifiers list
 2179  * \param obj CTL element identifier list
 2180  * \param idx Index of entry
 2181  * \return CTL element index
 2182  */
 2183 unsigned int snd_ctl_elem_list_get_index(const snd_ctl_elem_list_t *obj, unsigned int idx)
 2184 {
 2185     assert(obj);
 2186     assert(idx < obj->used);
 2187     return obj->pids[idx].index;
 2188 }
 2189 
 2190 /**
 2191  * \brief get size of #snd_ctl_elem_info_t
 2192  * \return size in bytes
 2193  */
 2194 size_t snd_ctl_elem_info_sizeof()
 2195 {
 2196     return sizeof(snd_ctl_elem_info_t);
 2197 }
 2198 
 2199 /**
 2200  * \brief allocate an invalid #snd_ctl_elem_info_t using standard malloc
 2201  * \param ptr returned pointer
 2202  * \return 0 on success otherwise negative error code
 2203  */
 2204 int snd_ctl_elem_info_malloc(snd_ctl_elem_info_t **ptr)
 2205 {
 2206     assert(ptr);
 2207     *ptr = calloc(1, sizeof(snd_ctl_elem_info_t));
 2208     if (!*ptr)
 2209         return -ENOMEM;
 2210     return 0;
 2211 }
 2212 
 2213 /**
 2214  * \brief frees a previously allocated #snd_ctl_elem_info_t
 2215  * \param obj pointer to object to free
 2216  */
 2217 void snd_ctl_elem_info_free(snd_ctl_elem_info_t *obj)
 2218 {
 2219     free(obj);
 2220 }
 2221 
 2222 /**
 2223  * \brief clear given #snd_ctl_elem_info_t object
 2224  * \param obj pointer to object to clear
 2225  */
 2226 void snd_ctl_elem_info_clear(snd_ctl_elem_info_t *obj)
 2227 {
 2228     memset(obj, 0, sizeof(snd_ctl_elem_info_t));
 2229 }
 2230 
 2231 /**
 2232  * \brief copy one #snd_ctl_elem_info_t to another
 2233  * \param dst pointer to destination
 2234  * \param src pointer to source
 2235  */
 2236 void snd_ctl_elem_info_copy(snd_ctl_elem_info_t *dst, const snd_ctl_elem_info_t *src)
 2237 {
 2238     assert(dst && src);
 2239     *dst = *src;
 2240 }
 2241 
 2242 /**
 2243  * \brief Get type from a CTL element id/info
 2244  * \param obj CTL element id/info
 2245  * \return CTL element content type
 2246  */
 2247 snd_ctl_elem_type_t snd_ctl_elem_info_get_type(const snd_ctl_elem_info_t *obj)
 2248 {
 2249     assert(obj);
 2250     return obj->type;
 2251 }
 2252 
 2253 /**
 2254  * \brief Get info about readability from a CTL element id/info
 2255  * \param obj CTL element id/info
 2256  * \return 0 if element is not readable, 1 if element is readable
 2257  */
 2258 int snd_ctl_elem_info_is_readable(const snd_ctl_elem_info_t *obj)
 2259 {
 2260     assert(obj);
 2261     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_READ);
 2262 }
 2263 
 2264 /**
 2265  * \brief Get info about writability from a CTL element id/info
 2266  * \param obj CTL element id/info
 2267  * \return 0 if element is not writable, 1 if element is not writable
 2268  */
 2269 int snd_ctl_elem_info_is_writable(const snd_ctl_elem_info_t *obj)
 2270 {
 2271     assert(obj);
 2272     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_WRITE);
 2273 }
 2274 
 2275 /**
 2276  * \brief Get info about notification feasibility from a CTL element id/info
 2277  * \param obj CTL element id/info
 2278  * \return 0 if all element value changes are notified to subscribed applications, 1 otherwise
 2279  */
 2280 int snd_ctl_elem_info_is_volatile(const snd_ctl_elem_info_t *obj)
 2281 {
 2282     assert(obj);
 2283     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_VOLATILE);
 2284 }
 2285 
 2286 /**
 2287  * \brief Get info about status from a CTL element id/info
 2288  * \param obj CTL element id/info
 2289  * \return 0 if element value is not active, 1 if is active
 2290  */
 2291 int snd_ctl_elem_info_is_inactive(const snd_ctl_elem_info_t *obj)
 2292 {
 2293     assert(obj);
 2294     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_INACTIVE);
 2295 }
 2296 
 2297 /**
 2298  * \brief Get info whether an element is locked
 2299  * \param obj CTL element id/info
 2300  * \return 0 if element value is currently changeable, 1 if it's locked by another application
 2301  */
 2302 int snd_ctl_elem_info_is_locked(const snd_ctl_elem_info_t *obj)
 2303 {
 2304     assert(obj);
 2305     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_LOCK);
 2306 }
 2307 
 2308 /**
 2309  * \brief Get info if I own an element
 2310  * \param obj CTL element id/info
 2311  * \return 0 if element value is currently changeable, 1 if it's locked by another application
 2312  */
 2313 int snd_ctl_elem_info_is_owner(const snd_ctl_elem_info_t *obj)
 2314 {
 2315     assert(obj);
 2316     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_OWNER);
 2317 }
 2318 
 2319 /**
 2320  * \brief Get info if it's a user element
 2321  * \param obj CTL element id/info
 2322  * \return 0 if element value is a system element, 1 if it's a user-created element
 2323  */
 2324 int snd_ctl_elem_info_is_user(const snd_ctl_elem_info_t *obj)
 2325 {
 2326     assert(obj);
 2327     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_USER);
 2328 }
 2329 
 2330 /**
 2331  * \brief Get info about TLV readability from a CTL element id/info
 2332  * \param obj CTL element id/info
 2333  * \return 0 if element's TLV is not readable, 1 if element's TLV is readable
 2334  */
 2335 int snd_ctl_elem_info_is_tlv_readable(const snd_ctl_elem_info_t *obj)
 2336 {
 2337     assert(obj);
 2338     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_TLV_READ);
 2339 }
 2340 
 2341 /**
 2342  * \brief Get info about TLV writeability from a CTL element id/info
 2343  * \param obj CTL element id/info
 2344  * \return 0 if element's TLV is not writable, 1 if element's TLV is writable
 2345  */
 2346 int snd_ctl_elem_info_is_tlv_writable(const snd_ctl_elem_info_t *obj)
 2347 {
 2348     assert(obj);
 2349     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_TLV_WRITE);
 2350 }
 2351 
 2352 /**
 2353  * \brief Get info about TLV command possibility from a CTL element id/info
 2354  * \param obj CTL element id/info
 2355  * \return 0 if element's TLV command is not possible, 1 if element's TLV command is supported
 2356  */
 2357 int snd_ctl_elem_info_is_tlv_commandable(const snd_ctl_elem_info_t *obj)
 2358 {
 2359     assert(obj);
 2360     return !!(obj->access & SNDRV_CTL_ELEM_ACCESS_TLV_COMMAND);
 2361 }
 2362 
 2363 /**
 2364  * \brief (DEPRECATED) Get info about values passing policy from a CTL element value
 2365  * \param obj CTL element id/info
 2366  * \return 0 if element value need to be passed by contents, 1 if need to be passed with a pointer
 2367  */
 2368 int snd_ctl_elem_info_is_indirect(const snd_ctl_elem_info_t *obj)
 2369 {
 2370     assert(obj);
 2371     return 0;
 2372 }
 2373 link_warning(snd_ctl_elem_info_is_indirect, "Warning: snd_ctl_elem_info_is_indirect is deprecated, do not use it");
 2374 
 2375 /**
 2376  * \brief Get owner of a locked element
 2377  * \param obj CTL element id/info
 2378  * \return value entries count
 2379  */
 2380 pid_t snd_ctl_elem_info_get_owner(const snd_ctl_elem_info_t *obj)
 2381 {
 2382     assert(obj);
 2383     return obj->owner;
 2384 }
 2385 
 2386 /**
 2387  * \brief Get number of value entries from a CTL element id/info
 2388  * \param obj CTL element id/info
 2389  * \return value entries count
 2390  */
 2391 unsigned int snd_ctl_elem_info_get_count(const snd_ctl_elem_info_t *obj)
 2392 {
 2393     assert(obj);
 2394     return obj->count;
 2395 }
 2396 
 2397 /**
 2398  * \brief Get minimum value from a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/info
 2399  * \param obj CTL element id/info
 2400  * \return Minimum value
 2401  */
 2402 long snd_ctl_elem_info_get_min(const snd_ctl_elem_info_t *obj)
 2403 {
 2404     assert(obj);
 2405     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER);
 2406     return obj->value.integer.min;
 2407 }
 2408 
 2409 /**
 2410  * \brief Get maximum value from a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/info
 2411  * \param obj CTL element id/info
 2412  * \return Maximum value
 2413  */
 2414 long snd_ctl_elem_info_get_max(const snd_ctl_elem_info_t *obj)
 2415 {
 2416     assert(obj);
 2417     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER);
 2418     return obj->value.integer.max;
 2419 }
 2420 
 2421 /**
 2422  * \brief Get value step from a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/info
 2423  * \param obj CTL element id/info
 2424  * \return Step
 2425  */
 2426 long snd_ctl_elem_info_get_step(const snd_ctl_elem_info_t *obj)
 2427 {
 2428     assert(obj);
 2429     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER);
 2430     return obj->value.integer.step;
 2431 }
 2432 
 2433 /**
 2434  * \brief Get minimum value from a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info
 2435  * \param obj CTL element id/info
 2436  * \return Minimum value
 2437  */
 2438 long long snd_ctl_elem_info_get_min64(const snd_ctl_elem_info_t *obj)
 2439 {
 2440     assert(obj);
 2441     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER64);
 2442     return obj->value.integer64.min;
 2443 }
 2444 
 2445 /**
 2446  * \brief Get maximum value from a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info
 2447  * \param obj CTL element id/info
 2448  * \return Maximum value
 2449  */
 2450 long long snd_ctl_elem_info_get_max64(const snd_ctl_elem_info_t *obj)
 2451 {
 2452     assert(obj);
 2453     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER64);
 2454     return obj->value.integer64.max;
 2455 }
 2456 
 2457 /**
 2458  * \brief Get value step from a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/info
 2459  * \param obj CTL element id/info
 2460  * \return Step
 2461  */
 2462 long long snd_ctl_elem_info_get_step64(const snd_ctl_elem_info_t *obj)
 2463 {
 2464     assert(obj);
 2465     assert(obj->type == SND_CTL_ELEM_TYPE_INTEGER64);
 2466     return obj->value.integer64.step;
 2467 }
 2468 
 2469 /**
 2470  * \brief Get number of items available from a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info
 2471  * \param obj CTL element id/info
 2472  * \return items count
 2473  */
 2474 unsigned int snd_ctl_elem_info_get_items(const snd_ctl_elem_info_t *obj)
 2475 {
 2476     assert(obj);
 2477     assert(obj->type == SND_CTL_ELEM_TYPE_ENUMERATED);
 2478     return obj->value.enumerated.items;
 2479 }
 2480 
 2481 /**
 2482  * \brief Select item in a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info
 2483  * \param obj CTL element id/info
 2484  * \param val item number
 2485  */
 2486 void snd_ctl_elem_info_set_item(snd_ctl_elem_info_t *obj, unsigned int val)
 2487 {
 2488     assert(obj);
 2489     obj->value.enumerated.item = val;
 2490 }
 2491 
 2492 /**
 2493  * \brief Get name for selected item in a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/info
 2494  * \param obj CTL element id/info
 2495  * \return name of chosen item
 2496  */
 2497 const char *snd_ctl_elem_info_get_item_name(const snd_ctl_elem_info_t *obj)
 2498 {
 2499     assert(obj);
 2500     assert(obj->type == SND_CTL_ELEM_TYPE_ENUMERATED);
 2501     return obj->value.enumerated.name;
 2502 }
 2503 
 2504 /**
 2505  * \brief Get count of dimensions for given element
 2506  * \param obj CTL element id/info
 2507  * \return zero value if no dimensions are defined, otherwise positive value with count of dimensions
 2508  *
 2509  * \deprecated  Since 1.1.5
 2510  * #snd_ctl_elem_info_get_dimensions is deprecated without any replacement.
 2511  */
 2512 #ifndef DOXYGEN
 2513 EXPORT_SYMBOL int INTERNAL(snd_ctl_elem_info_get_dimensions)(const snd_ctl_elem_info_t *obj)
 2514 #else
 2515 int snd_ctl_elem_info_get_dimensions(const snd_ctl_elem_info_t *obj)
 2516 #endif
 2517 {
 2518     int i;
 2519 
 2520     assert(obj);
 2521     for (i = 3; i >= 0; i--)
 2522         if (obj->dimen.d[i])
 2523             break;
 2524     return i + 1;
 2525 }
 2526 use_default_symbol_version(__snd_ctl_elem_info_get_dimensions, snd_ctl_elem_info_get_dimensions, ALSA_0.9.3);
 2527 
 2528 /**
 2529  * \brief Get specified of dimension width for given element
 2530  * \param obj CTL element id/info
 2531  * \param idx The dimension index
 2532  * \return zero value if no dimension width is defined, otherwise positive value with with of specified dimension
 2533  *
 2534  * \deprecated  Since 1.1.5
 2535  * #snd_ctl_elem_info_get_dimension is deprecated without any replacement.
 2536  */
 2537 #ifndef DOXYGEN
 2538 EXPORT_SYMBOL int INTERNAL(snd_ctl_elem_info_get_dimension)(const snd_ctl_elem_info_t *obj, unsigned int idx)
 2539 #else
 2540 int snd_ctl_elem_info_get_dimension(const snd_ctl_elem_info_t *obj, unsigned int idx)
 2541 #endif
 2542 {
 2543     assert(obj);
 2544     if (idx > 3)
 2545         return 0;
 2546     return obj->dimen.d[idx];
 2547 }
 2548 use_default_symbol_version(__snd_ctl_elem_info_get_dimension, snd_ctl_elem_info_get_dimension, ALSA_0.9.3);
 2549 
 2550 /**
 2551  * \brief Set width to a specified dimension level of given element information.
 2552  * \param info Information of an element.
 2553  * \param dimension Dimension width for each level by member unit.
 2554  * \return Zero on success, otherwise a negative error code.
 2555  *
 2556  * \par Errors:
 2557  * <dl>
 2558  * <dt>-EINVAL
 2559  * <dd>Invalid arguments are given as parameters.
 2560  * </dl>
 2561  *
 2562  * \par Compatibility:
 2563  * This function is added in version 1.1.2.
 2564  *
 2565  * \deprecated Since 1.1.5
 2566  * #snd_ctl_elem_info_set_dimension is deprecated without any replacement.
 2567  */
 2568 int snd_ctl_elem_info_set_dimension(snd_ctl_elem_info_t *info,
 2569                     const int dimension[4])
 2570 {
 2571     unsigned int i;
 2572 
 2573     if (info == NULL)
 2574         return -EINVAL;
 2575 
 2576     for (i = 0; i < ARRAY_SIZE(info->dimen.d); i++) {
 2577         if (dimension[i] < 0)
 2578             return -EINVAL;
 2579 
 2580         info->dimen.d[i] = dimension[i];
 2581     }
 2582 
 2583     return 0;
 2584 }
 2585 
 2586 /**
 2587  * \brief Get CTL element identifier of a CTL element id/info
 2588  * \param obj CTL element id/info
 2589  * \param ptr Pointer to returned CTL element identifier
 2590  */
 2591 void snd_ctl_elem_info_get_id(const snd_ctl_elem_info_t *obj, snd_ctl_elem_id_t *ptr)
 2592 {
 2593     assert(obj && ptr);
 2594     *ptr = obj->id;
 2595 }
 2596 
 2597 /**
 2598  * \brief Get element numeric identifier of a CTL element id/info
 2599  * \param obj CTL element id/info
 2600  * \return element numeric identifier
 2601  */
 2602 unsigned int snd_ctl_elem_info_get_numid(const snd_ctl_elem_info_t *obj)
 2603 {
 2604     assert(obj);
 2605     return obj->id.numid;
 2606 }
 2607 
 2608 /**
 2609  * \brief Get interface part of CTL element identifier of a CTL element id/info
 2610  * \param obj CTL element id/info
 2611  * \return interface part of element identifier
 2612  */
 2613 snd_ctl_elem_iface_t snd_ctl_elem_info_get_interface(const snd_ctl_elem_info_t *obj)
 2614 {
 2615     assert(obj);
 2616     return obj->id.iface;
 2617 }
 2618 
 2619 /**
 2620  * \brief Get device part of CTL element identifier of a CTL element id/info
 2621  * \param obj CTL element id/info
 2622  * \return device part of element identifier
 2623  */
 2624 unsigned int snd_ctl_elem_info_get_device(const snd_ctl_elem_info_t *obj)
 2625 {
 2626     assert(obj);
 2627     return obj->id.device;
 2628 }
 2629 
 2630 /**
 2631  * \brief Get subdevice part of CTL element identifier of a CTL element id/info
 2632  * \param obj CTL element id/info
 2633  * \return subdevice part of element identifier
 2634  */
 2635 unsigned int snd_ctl_elem_info_get_subdevice(const snd_ctl_elem_info_t *obj)
 2636 {
 2637     assert(obj);
 2638     return obj->id.subdevice;
 2639 }
 2640 
 2641 /**
 2642  * \brief Get name part of CTL element identifier of a CTL element id/info
 2643  * \param obj CTL element id/info
 2644  * \return name part of element identifier
 2645  */
 2646 const char *snd_ctl_elem_info_get_name(const snd_ctl_elem_info_t *obj)
 2647 {
 2648     assert(obj);
 2649     return (const char *)obj->id.name;
 2650 }
 2651 
 2652 /**
 2653  * \brief Get index part of CTL element identifier of a CTL element id/info
 2654  * \param obj CTL element id/info
 2655  * \return index part of element identifier
 2656  */
 2657 unsigned int snd_ctl_elem_info_get_index(const snd_ctl_elem_info_t *obj)
 2658 {
 2659     assert(obj);
 2660     return obj->id.index;
 2661 }
 2662 
 2663 /**
 2664  * \brief Set CTL element identifier of a CTL element id/info
 2665  * \param obj CTL element id/info
 2666  * \param ptr CTL element identifier
 2667  */
 2668 void snd_ctl_elem_info_set_id(snd_ctl_elem_info_t *obj, const snd_ctl_elem_id_t *ptr)
 2669 {
 2670     assert(obj && ptr);
 2671     obj->id = *ptr;
 2672 }
 2673 
 2674 /**
 2675  * \brief Set element numeric identifier of a CTL element id/info
 2676  * \param obj CTL element id/info
 2677  * \param val element numeric identifier
 2678  */
 2679 void snd_ctl_elem_info_set_numid(snd_ctl_elem_info_t *obj, unsigned int val)
 2680 {
 2681     assert(obj);
 2682     obj->id.numid = val;
 2683 }
 2684 
 2685 /**
 2686  * \brief Set interface part of CTL element identifier of a CTL element id/info
 2687  * \param obj CTL element id/info
 2688  * \param val interface part of element identifier
 2689  */
 2690 void snd_ctl_elem_info_set_interface(snd_ctl_elem_info_t *obj, snd_ctl_elem_iface_t val)
 2691 {
 2692     assert(obj);
 2693     obj->id.iface = val;
 2694 }
 2695 
 2696 /**
 2697  * \brief Set device part of CTL element identifier of a CTL element id/info
 2698  * \param obj CTL element id/info
 2699  * \param val device part of element identifier
 2700  */
 2701 void snd_ctl_elem_info_set_device(snd_ctl_elem_info_t *obj, unsigned int val)
 2702 {
 2703     assert(obj);
 2704     obj->id.device = val;
 2705 }
 2706 
 2707 /**
 2708  * \brief Set subdevice part of CTL element identifier of a CTL element id/info
 2709  * \param obj CTL element id/info
 2710  * \param val subdevice part of element identifier
 2711  */
 2712 void snd_ctl_elem_info_set_subdevice(snd_ctl_elem_info_t *obj, unsigned int val)
 2713 {
 2714     assert(obj);
 2715     obj->id.subdevice = val;
 2716 }
 2717 
 2718 /**
 2719  * \brief Set name part of CTL element identifier of a CTL element id/info
 2720  * \param obj CTL element id/info
 2721  * \param val name part of element identifier
 2722  */
 2723 void snd_ctl_elem_info_set_name(snd_ctl_elem_info_t *obj, const char *val)
 2724 {
 2725     assert(obj);
 2726     snd_strlcpy((char *)obj->id.name, val, sizeof(obj->id.name));
 2727 }
 2728 
 2729 /**
 2730  * \brief Set index part of CTL element identifier of a CTL element id/info
 2731  * \param obj CTL element id/info
 2732  * \param val index part of element identifier
 2733  */
 2734 void snd_ctl_elem_info_set_index(snd_ctl_elem_info_t *obj, unsigned int val)
 2735 {
 2736     assert(obj);
 2737     obj->id.index = val;
 2738 }
 2739 
 2740 /**
 2741  * \brief Get size of data structure for an element.
 2742  * \return Size in bytes.
 2743  */
 2744 size_t snd_ctl_elem_value_sizeof()
 2745 {
 2746     return sizeof(snd_ctl_elem_value_t);
 2747 }
 2748 
 2749 /**
 2750  * \brief Allocate an invalid #snd_ctl_elem_value_t using standard malloc(3).
 2751  * \param ptr Returned pointer for data of an element.
 2752  * \return 0 on success otherwise negative error code.
 2753  */
 2754 int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
 2755 {
 2756     assert(ptr);
 2757     *ptr = calloc(1, sizeof(snd_ctl_elem_value_t));
 2758     if (!*ptr)
 2759         return -ENOMEM;
 2760     return 0;
 2761 }
 2762 
 2763 /**
 2764  * \brief Frees a previously allocated data of an element.
 2765  * \param obj Data of an element.
 2766  */
 2767 void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
 2768 {
 2769     free(obj);
 2770 }
 2771 
 2772 /**
 2773  * \brief Clear given data of an element.
 2774  * \param obj Data of an element.
 2775  */
 2776 void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj)
 2777 {
 2778     memset(obj, 0, sizeof(snd_ctl_elem_value_t));
 2779 }
 2780 
 2781 /**
 2782  * \brief Copy two data of elements.
 2783  * \param dst Pointer to destination.
 2784  * \param src Pointer to source.
 2785  */
 2786 void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst,
 2787                  const snd_ctl_elem_value_t *src)
 2788 {
 2789     assert(dst && src);
 2790     *dst = *src;
 2791 }
 2792 
 2793 /**
 2794  * \brief Compare one data of an element to the other.
 2795  * \param left Pointer to first data.
 2796  * \param right Pointer to second data.
 2797  * \return 0 on match, less than or greater than otherwise, see memcmp(3).
 2798  */
 2799 int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left,
 2800                    const snd_ctl_elem_value_t *right)
 2801 {
 2802     assert(left && right);
 2803     return memcmp(left, right, sizeof(*left));
 2804 }
 2805 
 2806 /**
 2807  * \brief Get element identifier from given data of an element.
 2808  * \param obj Data of an element.
 2809  * \param ptr Pointer for element identifier.
 2810  */
 2811 void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr)
 2812 {
 2813     assert(obj && ptr);
 2814     *ptr = obj->id;
 2815 }
 2816 
 2817 /**
 2818  * \brief Get element numeric identifier from given data of an element.
 2819  * \param obj Data of an element.
 2820  * \return Element numeric identifier.
 2821  */
 2822 unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj)
 2823 {
 2824     assert(obj);
 2825     return obj->id.numid;
 2826 }
 2827 
 2828 /**
 2829  * \brief Get interface part of element identifier from given data of an
 2830  *    element.
 2831  * \param obj Data of an element.
 2832  * \return Interface part of element identifier.
 2833  */
 2834 snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj)
 2835 {
 2836     assert(obj);
 2837     return obj->id.iface;
 2838 }
 2839 
 2840 /**
 2841  * \brief Get device part of element identifier from given data of an element.
 2842  * \param obj Data of an element.
 2843  * \return Device part of element identifier.
 2844  */
 2845 unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj)
 2846 {
 2847     assert(obj);
 2848     return obj->id.device;
 2849 }
 2850 
 2851 /**
 2852  * \brief Get subdevice part of element identifier from given data of an
 2853  *    element.
 2854  * \param obj Data of an element.
 2855  * \return Subdevice part of element identifier.
 2856  */
 2857 unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj)
 2858 {
 2859     assert(obj);
 2860     return obj->id.subdevice;
 2861 }
 2862 
 2863 /**
 2864  * \brief Get name part of element identifier from given data of an element.
 2865  * \param obj Data of an element.
 2866  * \return Name part of element identifier.
 2867  */
 2868 const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj)
 2869 {
 2870     assert(obj);
 2871     return (const char *)obj->id.name;
 2872 }
 2873 
 2874 /**
 2875  * \brief Get index part of element identifier from given data of an element.
 2876  * \param obj Data of an element.
 2877  * \return Index part of element identifier.
 2878  */
 2879 unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj)
 2880 {
 2881     assert(obj);
 2882     return obj->id.index;
 2883 }
 2884 
 2885 /**
 2886  * \brief Set element identifier to given data of an element.
 2887  * \param obj Data of an element.
 2888  * \param ptr Pointer to an element identifier.
 2889  */
 2890 void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr)
 2891 {
 2892     assert(obj && ptr);
 2893     obj->id = *ptr;
 2894 }
 2895 
 2896 /**
 2897  * \brief Set numeric identifier to given data of an element.
 2898  * \param obj Data of an element.
 2899  * \param val Value for numeric identifier.
 2900  */
 2901 void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val)
 2902 {
 2903     assert(obj);
 2904     obj->id.numid = val;
 2905 }
 2906 
 2907 /**
 2908  * \brief Set interface part of element identifier to given data of an element.
 2909  * \param obj Data of an element.
 2910  * \param val Value for interface part of element identifier.
 2911  */
 2912 void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val)
 2913 {
 2914     assert(obj);
 2915     obj->id.iface = val;
 2916 }
 2917 
 2918 /**
 2919  * \brief Set device part of element identifier to given data of an element.
 2920  * \param obj Data of an element.
 2921  * \param val Value for device part of element identifier.
 2922  */
 2923 void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val)
 2924 {
 2925     assert(obj);
 2926     obj->id.device = val;
 2927 }
 2928 
 2929 /**
 2930  * \brief Set subdevice part of element identifier to given data of an element.
 2931  * \param obj Data of an element.
 2932  * \param val Value for subdevice part of element identifier.
 2933  */
 2934 void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val)
 2935 {
 2936     assert(obj);
 2937     obj->id.subdevice = val;
 2938 }
 2939 
 2940 /**
 2941  * \brief Set name part of element identifier to given data of an element.
 2942  * \param obj Data of an element.
 2943  * \param val Value for name part of element identifier,
 2944  */
 2945 void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val)
 2946 {
 2947     assert(obj);
 2948     snd_strlcpy((char *)obj->id.name, val, sizeof(obj->id.name));
 2949 }
 2950 
 2951 /**
 2952  * \brief Set index part of element identifier to given data of an element.
 2953  * \param obj Data of an element.
 2954  * \param val Value for index part of element identifier.
 2955  */
 2956 void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val)
 2957 {
 2958     assert(obj);
 2959     obj->id.index = val;
 2960 }
 2961 
 2962 /**
 2963  * \brief Get value of a specified member from given data as an element of
 2964  *    boolean type.
 2965  * \param obj Data of an element.
 2966  * \param idx Index of member in the element.
 2967  * \return Value for the member.
 2968  */ 
 2969 int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx)
 2970 {
 2971     assert(obj);
 2972     assert(idx < ARRAY_SIZE(obj->value.integer.value));
 2973     return obj->value.integer.value[idx];
 2974 }
 2975 
 2976 /**
 2977  * \brief Get value of a specified member from given data as an element of
 2978  *    integer type.
 2979  * \param obj Data of an element.
 2980  * \param idx Index of member in the element.
 2981  * \return Value for the member.
 2982  */ 
 2983 long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx)
 2984 {
 2985     assert(obj);
 2986     assert(idx < ARRAY_SIZE(obj->value.integer.value));
 2987     return obj->value.integer.value[idx];
 2988 }
 2989 
 2990 /**
 2991  * \brief Get value of a specified member from given data as an element of
 2992  *    integer64 type.
 2993  * \param obj Data of an element.
 2994  * \param idx Index of member in the element.
 2995  * \return Value for the member.
 2996  */ 
 2997 long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx)
 2998 {
 2999     assert(obj);
 3000     assert(idx < ARRAY_SIZE(obj->value.integer64.value));
 3001     return obj->value.integer64.value[idx];
 3002 }
 3003 
 3004 /**
 3005  * \brief Get value of a specified member from given data as an element of
 3006  *    enumerated type.
 3007  * \param obj Data of an element.
 3008  * \param idx Index of member in the element.
 3009  * \return Value for the member. This is an index of name set in the element.
 3010  */ 
 3011 unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx)
 3012 {
 3013     assert(obj);
 3014     assert(idx < ARRAY_SIZE(obj->value.enumerated.item));
 3015     return obj->value.enumerated.item[idx];
 3016 }
 3017 
 3018 /**
 3019  * \brief Get value of a specified member from given data as an element of
 3020  *    bytes type.
 3021  * \param obj Data of an element.
 3022  * \param idx Index of member in the element.
 3023  * \return Value for the member.
 3024  */ 
 3025 unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx)
 3026 {
 3027     assert(obj);
 3028     assert(idx < ARRAY_SIZE(obj->value.bytes.data));
 3029     return obj->value.bytes.data[idx];
 3030 }
 3031 
 3032 /**
 3033  * \brief Set value of a specified member to given data as an element of
 3034  *    boolean type.
 3035  * \param obj Data of an element.
 3036  * \param idx Index of member in the element.
 3037  * \param val Value for the member.
 3038  */ 
 3039 void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
 3040 {
 3041     assert(obj);
 3042     assert(idx < ARRAY_SIZE(obj->value.integer.value));
 3043     obj->value.integer.value[idx] = val;
 3044 }
 3045 
 3046 /**
 3047  * \brief Set value of a specified member to given data as an element of
 3048  *    integer type.
 3049  * \param obj Data of an element.
 3050  * \param idx Index of member in the element.
 3051  * \param val Value for the member.
 3052  */ 
 3053 void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
 3054 {
 3055     assert(obj);
 3056     assert(idx < ARRAY_SIZE(obj->value.integer.value));
 3057     obj->value.integer.value[idx] = val;
 3058 }
 3059 
 3060 /**
 3061  * \brief Set value of a specified member to given data as an element of
 3062  *    integer64 type.
 3063  * \param obj Data of an element.
 3064  * \param idx Index of member in the element.
 3065  * \param val Value for the member.
 3066  */ 
 3067 void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val)
 3068 {
 3069     assert(obj);
 3070     assert(idx < ARRAY_SIZE(obj->value.integer64.value));
 3071     obj->value.integer64.value[idx] = val;
 3072 }
 3073 
 3074 /**
 3075  * \brief Set value of a specified member to given data as an element of
 3076  *    enumerated type.
 3077  * \param obj Data of an element.
 3078  * \param idx Index of member in the element.
 3079  * \param val Value for the member.
 3080  */ 
 3081 void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val)
 3082 {
 3083     assert(obj);
 3084     assert(idx < ARRAY_SIZE(obj->value.enumerated.item));
 3085     obj->value.enumerated.item[idx] = val;
 3086 }
 3087 
 3088 /**
 3089  * \brief Set value for a specified member to given data as an element of byte
 3090  *    type.
 3091  * \param obj Data of an element.
 3092  * \param idx Index of member in the element.
 3093  * \param val Value for the member.
 3094  */ 
 3095 void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val)
 3096 {
 3097     assert(obj);
 3098     assert(idx < ARRAY_SIZE(obj->value.bytes.data));
 3099     obj->value.bytes.data[idx] = val;
 3100 }
 3101 
 3102 /**
 3103  * \brief Set values to given data as an element of bytes type.
 3104  * \param obj Data of an element.
 3105  * \param data Pointer for byte array.
 3106  * \param size The number of bytes included in the memory block.
 3107  */
 3108 void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size)
 3109 {
 3110     assert(obj);
 3111     assert(size <= ARRAY_SIZE(obj->value.bytes.data));
 3112     memcpy(obj->value.bytes.data, data, size);
 3113 }
 3114 
 3115 /**
 3116  * \brief Get memory block from given data as an element of bytes type.
 3117  * \param obj Data of an element.
 3118  * \return Pointer for byte array.
 3119  */ 
 3120 const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
 3121 {
 3122     assert(obj);
 3123     return obj->value.bytes.data;
 3124 }
 3125 
 3126 /**
 3127  * \brief Get value from given data to given pointer as an element of IEC958
 3128  *    type.
 3129  * \param obj Data of an element.
 3130  * \param ptr Pointer to IEC958 data.
 3131  */ 
 3132 void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr)
 3133 {
 3134     assert(obj && ptr);
 3135     memcpy(ptr, &obj->value.iec958, sizeof(*ptr));
 3136 }
 3137 
 3138 /**
 3139  * \brief Set value from given pointer to given data as an element of IEC958
 3140  *    type.
 3141  * \param obj Data of an element.
 3142  * \param ptr Pointer to IEC958 data.
 3143  */ 
 3144 void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr)
 3145 {
 3146     assert(obj && ptr);
 3147     memcpy(&obj->value.iec958, ptr, sizeof(obj->value.iec958));
 3148 }
 3149