From patchwork Wed Sep 2 09:27:27 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Tanjeff-N. Moos" X-Patchwork-Id: 291885 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-13.0 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID, HEADER_FROM_DIFFERENT_DOMAINS, INCLUDES_PATCH, MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED,USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9C2DEC433E2 for ; Wed, 2 Sep 2020 09:30:02 +0000 (UTC) Received: from alsa0.perex.cz (alsa0.perex.cz [77.48.224.243]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 1FC5220829 for ; Wed, 2 Sep 2020 09:30:02 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=alsa-project.org header.i=@alsa-project.org header.b="vL0CfSS6"; dkim=fail reason="signature verification failed" (1024-bit key) header.d=cccmz.de header.i=@cccmz.de header.b="sPX7Nb/q" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1FC5220829 Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=cccmz.de Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=alsa-devel-bounces@alsa-project.org Received: from alsa1.perex.cz (alsa1.perex.cz [207.180.221.201]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by alsa0.perex.cz (Postfix) with ESMTPS id 6BEDA1815; Wed, 2 Sep 2020 11:29:10 +0200 (CEST) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa0.perex.cz 6BEDA1815 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=alsa-project.org; s=default; t=1599039000; bh=dd8olhPzucJ8ykH7LA+ZQmoQsnaSqo7DxGibW/culuo=; h=From:To:Subject:Date:In-Reply-To:References:Cc:List-Id: List-Unsubscribe:List-Archive:List-Post:List-Help:List-Subscribe: From; b=vL0CfSS6r4m/RTDaq/DszqcV9+9e6dCQFza/ziDDiSfH9nGqFGqFP1ZTPoNBrN1+J 8CxUugUONPrXpfmM4d7IGw2tV1tQH8KVU30pE+CP/o7DkvxbMtEgYFfft2dA5omWAC ptTKg05yOVvtyBgt+Hr7XgGCejeDWgnPzKeflbPE= Received: from alsa1.perex.cz (localhost.localdomain [127.0.0.1]) by alsa1.perex.cz (Postfix) with ESMTP id 27A24F80276; Wed, 2 Sep 2020 11:28:18 +0200 (CEST) Received: by alsa1.perex.cz (Postfix, from userid 50401) id E3A87F8024A; Wed, 2 Sep 2020 11:28:12 +0200 (CEST) Received: from mail.cccmz.de (mail.cccmz.de [IPv6:2a01:4f8:161:4283:1000::108]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by alsa1.perex.cz (Postfix) with ESMTPS id B1519F800F3 for ; Wed, 2 Sep 2020 11:28:01 +0200 (CEST) DKIM-Filter: OpenDKIM Filter v2.11.0 alsa1.perex.cz B1519F800F3 Authentication-Results: alsa1.perex.cz; dkim=pass (1024-bit key) header.d=cccmz.de header.i=@cccmz.de header.b="sPX7Nb/q" Received: from tanjeffs-laptop.fritz.box (x4db458da.dyn.telefonica.de [77.180.88.218]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: tanjeff@cccmz.de) by mail.cccmz.de (Postfix) with ESMTPSA id A3B3B17A298D; Wed, 2 Sep 2020 11:28:00 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=cccmz.de; s=2019; t=1599038880; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:in-reply-to:in-reply-to:references:references; bh=PvRXlzzx7syrF2s53nRxnbODukIZC/0cfOZg8HusSks=; b=sPX7Nb/qp8/OvakNVK54H6DtEGjaTQtKwCuf19AImzsC60SQpV3Iy6i+3zutbvJC+adaF9 MsDpeoZTOLEaCOO1WngucWTr7Joq0e2hyPs9gsfZRyQ0tnTVL4hxybiWwUjGWCCEzUXPX/ reycdtbknQuwy/sHGa+tPD0JqLo1noQ= From: "Tanjeff-N. Moos" To: alsa-devel@alsa-project.org Subject: [PATCH 2/2] control: Add documentation for snd_ctl_elem_value_*. Date: Wed, 2 Sep 2020 11:27:27 +0200 Message-Id: <20200902092727.2732-2-tanjeff@cccmz.de> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200902092727.2732-1-tanjeff@cccmz.de> References: <20200902092727.2732-1-tanjeff@cccmz.de> Cc: Takashi Iwai , "Tanjeff-N. Moos" X-BeenThere: alsa-devel@alsa-project.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: "Alsa-devel mailing list for ALSA developers - http://www.alsa-project.org" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: alsa-devel-bounces@alsa-project.org Sender: "Alsa-devel" Signed-off-by: Tanjeff-N. Moos --- include/control.h | 61 +++++- src/control/control.c | 454 ++++++++++++++++++++++++++++-------------- 2 files changed, 357 insertions(+), 158 deletions(-) diff --git a/include/control.h b/include/control.h index 9deec6f3..8766f440 100644 --- a/include/control.h +++ b/include/control.h @@ -130,7 +130,53 @@ typedef struct _snd_ctl_elem_list snd_ctl_elem_list_t; /** CTL element info container */ typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t; -/** CTL element value container */ +/** CTL element value container + * + * Contains the value(s) (i.e. members) of a single element. All + * values of a given element are of the same type. + * + * \par Memory management + * + * To access a value, a snd_ctl_elem_value_t must be allocated using + * snd_ctl_elem_value_alloca() or snd_ctl_elem_value_malloc(). When + * using the latter, it must be freed again using + * snd_ctl_elem_value_free(). + * + * \par Identifier + * + * Then, the ID must be filled. It is sufficient to fill only the + * numid, if known. Otherwise, interface type, device, subdevice, + * name, index must all be given. The following functions can be used + * to fill the ID: + * + * - snd_ctl_elem_value_set_id(): Set the ID. Requires an + * snd_ctl_elem_id_t object. + * - snd_ctl_elem_value_set_numid(): Set the numid. + * - Or use all of the following: + * + * - snd_ctl_elem_value_set_interface() + * - snd_ctl_elem_value_set_device() + * - snd_ctl_elem_value_set_subdevice() + * - snd_ctl_elem_value_set_name() + * - snd_ctl_elem_value_set_index() + * + * When communicating with the driver (snd_ctl_elem_read(), + * snd_ctl_elem_write()), and the numid was given, the interface, + * device, ... are filled (even if you set the before). When the numid + * is unset (i.e. it is 0), it is filled. + * + * \par Communicating with the driver + * + * After the value container was created and filled with the ID of the + * desired element, the value(s) can be fetched from the driver (and + * thus from the hardware) or written to the driver. + * + * To fetch a value, use snd_ctl_elem_read(). Thereafter, use the + * snd_ctl_elem_value_get_*() functions to obtain the actual value. + * + * To write a new value, first use a snd_ctl_elem_value_set_*() to set + * it, then call snd_ctl_elem_write() to write it to the driver. + */ typedef struct _snd_ctl_elem_value snd_ctl_elem_value_t; /** CTL event container */ @@ -529,11 +575,20 @@ int snd_ctl_elem_add_iec958(snd_ctl_t *ctl, const snd_ctl_elem_id_t *id); int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id); size_t snd_ctl_elem_value_sizeof(void); + /** \hideinitializer - * \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca - * \param ptr returned pointer + * \brief Allocate an invalid #snd_ctl_elem_value_t on the stack. + * + * Allocate space for a value object on the stack. The allocated + * memory need not be freed, because is on the stack. + * + * See snd_ctl_elem_value_t for details. + * + * \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address + * of the allocated space will returned here. */ #define snd_ctl_elem_value_alloca(ptr) __snd_alloca(ptr, snd_ctl_elem_value) + int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr); void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj); void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj); diff --git a/src/control/control.c b/src/control/control.c index 497a5399..08058c06 100644 --- a/src/control/control.c +++ b/src/control/control.c @@ -38,32 +38,39 @@ also an interface for notifying about control and structure changes. In ALSA control feature, each sound card can have control elements. The elements are managed according to below model. - - element set + - Element set + - A set of elements with the same attribute (i.e. name, get/put operations). Some element sets can be added to a sound card by drivers in kernel and userspace applications. - - element + + - Element + - A control element might be a master volume control, for example, or a read-only indicator, such as a sync status. An element has a type (e.g. - INTEGER or BOOLEAN) and - depending on the type - min/max values, a step - size, a set of possible values (for enums), etc. - - member + SNDRV_CTL_ELEM_TYPE_INTEGER or SNDRV_CTL_ELEM_TYPE_BOOLEAN) and - depending + on the type - min/max values, a step size, a set of possible values (for + enums), etc. + + - Member - - An element includes one or more member(s) to have a value. For - example, a stereo volume control element has two members (for - left/right). The members share the same properties (e.g. both - volume controls have the same min/max values). The value of each - member can be changed by both of userspace applications and - drivers in kernel. + - An element usually includes one or more member(s) to have a value. For + example, a stereo volume control element has two members (for left/right), + while a mono volume has only one member. The member count can be obtained + using snd_ctl_elem_info_get_count(). Elements of type + "SNDRV_CTL_ELEM_TYPE_BYTES" or "SNDRV_CTL_ELEM_TYPE_IEC958" have no members + at all (and thus no member count), they have just a single value. The + members share the same properties (e.g. both volume control members have + the same min/max values). The value of each member can be changed by both + of userspace applications and drivers in kernel. -\section identifying_elements Identifying the Elements +\section identifying_elements Identifying Elements Each element has the following identifying properties: - The numid (a numeric identifier, assigned when the sound card is detected, constant while the sound card is kept connected) - - The interface type (e.g. MIXER, CARD or PCM) - The device - The subdevice @@ -95,10 +102,10 @@ on. In addition, these functions can report the identifying properties. E.g. when the element is addressed using its numid, the functions complements the name, index, etc. -To access the values of a control, use the snd_ctl_elem_value*() -functions. These allow to get and set the actual values or -settings. It is also possible to get and set the ID values (such as -the numid or the name). +To access the members (i.e. values) of a control, use the +snd_ctl_elem_value*() functions. These allow to get and set the +actual values or settings. It is also possible to get and set the ID +values (such as the numid or the name). \section element_sets Element Sets @@ -931,10 +938,19 @@ int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id) } /** - * \brief Get CTL element value - * \param ctl CTL handle - * \param data Data of an element. - * \return 0 on success otherwise a negative error code + * \brief Get CTL element value. + * + * Read information from sound card. You must set the ID of the + * element before calling this function. + * + * See snd_ctl_elem_value_t for details. + * + * \param ctl CTL handle. + * \param data The element value. The ID must be set before calling + * the function, and the actual value will be returned + * here. + * + * \return 0 on success otherwise a negative error code. */ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data) { @@ -943,9 +959,16 @@ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *data) } /** - * \brief Set CTL element value - * \param ctl CTL handle - * \param data Data of an element. + * \brief Set CTL element value. + * + * Write new value(s) to the sound card. You must set the ID and the + * value of the element before calling this function. + * + * See snd_ctl_elem_value_t for details. + * + * \param ctl CTL handle. + * \param data The new value. + * * \retval 0 on success * \retval >0 on success when value was changed * \retval <0 a negative error code @@ -2877,9 +2900,16 @@ size_t snd_ctl_elem_value_sizeof() } /** - * \brief Allocate an invalid #snd_ctl_elem_value_t using standard malloc(3). - * \param ptr Returned pointer for data of an element. - * \return 0 on success otherwise negative error code. + * \brief Allocate an invalid #snd_ctl_elem_value_t on the heap. + * + * Allocate space for a value object on the head. The allocated memory + * must be freed using snd_ctl_elem_value_free(). + * + * See snd_ctl_elem_value_t for details. + * + * \param ptr Pointer to a snd_ctl_elem_value_t pointer. The address + * of the allocated space will be returned here. + * \return 0 on success, otherwise a negative error code. */ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr) { @@ -2891,8 +2921,10 @@ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr) } /** - * \brief Frees a previously allocated data of an element. - * \param obj Data of an element. + * \brief Free an #snd_ctl_elem_value_t previously allocated using + * snd_ctl_elem_value_malloc(). + * + * \param obj Pointer to the snd_ctl_elem_value_t. */ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj) { @@ -2901,6 +2933,9 @@ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj) /** * \brief Clear given data of an element. + * + * See snd_ctl_elem_value_t for details. + * * \param obj Data of an element. */ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj) @@ -2909,7 +2944,7 @@ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj) } /** - * \brief Copy two data of elements. + * \brief Bitwise copy of a snd_ctl_elem_value_t value. * \param dst Pointer to destination. * \param src Pointer to source. */ @@ -2921,9 +2956,10 @@ void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst, } /** - * \brief Compare one data of an element to the other. - * \param left Pointer to first data. - * \param right Pointer to second data. + * \brief Compare two snd_ctl_elem_value_t values, bytewise. + * + * \param left First value. + * \param right Second value. * \return 0 on match, less than or greater than otherwise, see memcmp(3). */ int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left, @@ -2934,9 +2970,13 @@ int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left, } /** - * \brief Get element identifier from given data of an element. - * \param obj Data of an element. - * \param ptr Pointer for element identifier. + * \brief Get the element identifier from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param ptr Pointer to an identifier object. The identifier is + * stored there. */ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr) { @@ -2945,9 +2985,12 @@ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_ } /** - * \brief Get element numeric identifier from given data of an element. - * \param obj Data of an element. - * \return Element numeric identifier. + * \brief Get the identifiers 'numid' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The numid. */ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj) { @@ -2956,10 +2999,12 @@ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj) } /** - * \brief Get interface part of element identifier from given data of an - * element. - * \param obj Data of an element. - * \return Interface part of element identifier. + * \brief Get the identifiers 'interface' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The interface part of element identifier. */ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj) { @@ -2968,9 +3013,12 @@ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t } /** - * \brief Get device part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Device part of element identifier. + * \brief Get the identifiers 'device' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The device part of element identifier. */ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj) { @@ -2979,10 +3027,12 @@ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj) } /** - * \brief Get subdevice part of element identifier from given data of an - * element. - * \param obj Data of an element. - * \return Subdevice part of element identifier. + * \brief Get the identifiers 'subdevice' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The subdevice part of element identifier. */ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj) { @@ -2991,9 +3041,12 @@ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj) } /** - * \brief Get name part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Name part of element identifier. + * \brief Get the identifiers 'name' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The "name" part of element identifier. */ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj) { @@ -3002,9 +3055,12 @@ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj) } /** - * \brief Get index part of element identifier from given data of an element. - * \param obj Data of an element. - * \return Index part of element identifier. + * \brief Get the identifiers 'index' part from the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \return The index part of element identifier. */ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj) { @@ -3012,10 +3068,14 @@ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj) return obj->id.index; } + /** - * \brief Set element identifier to given data of an element. - * \param obj Data of an element. - * \param ptr Pointer to an element identifier. + * \brief Set the element identifier within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param ptr The new identifier. */ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr) { @@ -3024,9 +3084,12 @@ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_ } /** - * \brief Set numeric identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for numeric identifier. + * \brief Set the identifiers 'numid' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new numid. */ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3035,9 +3098,12 @@ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val) } /** - * \brief Set interface part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for interface part of element identifier. + * \brief Set the identifiers 'interface' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new interface. */ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val) { @@ -3046,9 +3112,12 @@ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_if } /** - * \brief Set device part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for device part of element identifier. + * \brief Set the identifiers 'device' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new device. */ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3057,9 +3126,12 @@ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val) } /** - * \brief Set subdevice part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for subdevice part of element identifier. + * \brief Set the identifiers 'subdevice' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new subdevice. */ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3068,9 +3140,12 @@ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int va } /** - * \brief Set name part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for name part of element identifier, + * \brief Set the identifiers 'name' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new name. */ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val) { @@ -3079,9 +3154,12 @@ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val) } /** - * \brief Set index part of element identifier to given data of an element. - * \param obj Data of an element. - * \param val Value for index part of element identifier. + * \brief Set the identifiers 'index' part within the given element value. + * + * See snd_ctl_elem_value_t for more details. + * + * \param obj The element value. + * \param val The new index. */ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) { @@ -3090,12 +3168,16 @@ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) } /** - * \brief Get value of a specified member from given data as an element of - * boolean type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object + * \param idx The index of the member. + * \return The members value. + */ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3104,12 +3186,16 @@ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int } /** - * \brief Get value of a specified member from given data as an element of - * integer type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3118,12 +3204,16 @@ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned in } /** - * \brief Get value of a specified member from given data as an element of - * integer64 type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3132,12 +3222,16 @@ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsi } /** - * \brief Get value of a specified member from given data as an element of - * enumerated type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. This is an index of name set in the element. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type + * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It returns the index of the active item. See + * \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param idx The index of the requested member. + * \return The index of the active item. + */ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3146,12 +3240,16 @@ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, } /** - * \brief Get value of a specified member from given data as an element of - * bytes type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \return Value for the member. - */ + * \brief Get an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It + * returns the value of one member. See \ref snd_ctl_elem_value_t and \ref + * control for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \return The members value. + */ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx) { assert(obj); @@ -3160,12 +3258,16 @@ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsig } /** - * \brief Set value of a specified member to given data as an element of - * boolean type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BOOLEAN. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { assert(obj); @@ -3174,12 +3276,16 @@ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, } /** - * \brief Set value of a specified member to given data as an element of - * integer type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val) { assert(obj); @@ -3188,12 +3294,16 @@ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, } /** - * \brief Set value of a specified member to given data as an element of - * integer64 type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_INTEGER64. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val) { assert(obj); @@ -3202,12 +3312,16 @@ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int id } /** - * \brief Set value of a specified member to given data as an element of - * enumerated type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type + * SNDRV_CTL_ELEM_TYPE_ENUMERATED. It activates the specified item. See \ref + * snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param idx The index of the requested member. + * \param val The new index of the item to be activated. + */ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val) { assert(obj); @@ -3216,12 +3330,16 @@ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int i } /** - * \brief Set value for a specified member to given data as an element of byte - * type. - * \param obj Data of an element. - * \param idx Index of member in the element. - * \param val Value for the member. - */ + * \brief Set an element members value. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTE. It + * sets the value of one member. See \ref snd_ctl_elem_value_t and \ref control + * for more details. + * + * \param obj The element value object. + * \param idx The index of the member. + * \param val The new value. + */ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val) { assert(obj); @@ -3230,10 +3348,17 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un } /** - * \brief Set values to given data as an element of bytes type. - * \param obj Data of an element. - * \param data Pointer for byte array. - * \param size The number of bytes included in the memory block. + * \brief Replace the data stored within the element. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It + * replaces the data stored in the element. Note that "bytes" elements don't + * have members. They have only one single block of data. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param data Pointer to the new data. + * \param size The size of the new data, in bytes. */ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) { @@ -3243,10 +3368,17 @@ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) } /** - * \brief Get memory block from given data as an element of bytes type. - * \param obj Data of an element. - * \return Pointer for byte array. - */ + * \brief Get the data stored within the element. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_BYTES. It + * returns the data stored in the element. Note that "bytes" elements don't have + * members. They have only one single block of data. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \return Pointer to the elements data. + */ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) { assert(obj); @@ -3254,11 +3386,17 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) } /** - * \brief Get value from given data to given pointer as an element of IEC958 - * type. - * \param obj Data of an element. - * \param ptr Pointer to IEC958 data. - */ + * \brief Get an elements IEC958 data. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note that + * "IEC958" elements don't have members. They have only one single + * IEC958 information block. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param ptr Pointer to an IEC958 structure. The data is stored there. + */ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr) { assert(obj && ptr); @@ -3266,11 +3404,17 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9 } /** - * \brief Set value from given pointer to given data as an element of IEC958 - * type. - * \param obj Data of an element. - * \param ptr Pointer to IEC958 data. - */ + * \brief Set an elements IEC958 data. + * + * Use this function if the element is of type SNDRV_CTL_ELEM_TYPE_IEC958. Note + * that "IEC958" elements don't have members. They have only one single IEC958 + * information block. + * + * See \ref snd_ctl_elem_value_t and \ref control for more details. + * + * \param obj The element value object. + * \param ptr Pointer to the new IEC958 data. + */ void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr) { assert(obj && ptr);