[PATCH 2/2] control: Add documentation for snd_ctl_elem_value_*.
Tanjeff-N. Moos
tanjeff at cccmz.de
Wed Sep 2 11:27:27 CEST 2020
Signed-off-by: Tanjeff-N. Moos <tanjeff at cccmz.de>
---
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);
--
2.17.1
More information about the Alsa-devel
mailing list