mirrors/alsa-lib
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-lib.git synced 2025-11-03 09:01:52 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

ctl: improve comments for handling element data

Browse source 
Some parts of control API documentation are described with core-developer
friendly explanations. To usual developer such as me, they're quite hard
to understand.

This commit improves such comments for a part of APIs to handle data of
each element.

Signed-off-by: Takashi Sakamoto <o-takashi@sakamocchi.jp>
Signed-off-by: Takashi Iwai <tiwai@suse.de>
This commit is contained in:
Takashi Sakamoto 2016-06-15 23:57:38 +09:00 • committed by Takashi Iwai
parent f3c24de8c0
commit 90020c05f8
1 changed files with 131 additions and 115 deletions
Download patch file Download diff file Expand all files Collapse all files

246
src/control/control.c
View file

@ -482,7 +482,7 @@ int snd_ctl_elem_remove(snd_ctl_t *ctl, snd_ctl_elem_id_t *id)
/** /**
* \brief Get CTL element value * \brief Get CTL element value
* \param ctl CTL handle * \param ctl CTL handle
* \param control CTL element id/value pointer * \param obj Data of an element.
* \return 0 on success otherwise a negative error code * \return 0 on success otherwise a negative error code
*/ */
int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *control) int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *control)
@ -494,7 +494,7 @@ int snd_ctl_elem_read(snd_ctl_t *ctl, snd_ctl_elem_value_t *control)
/** /**
* \brief Set CTL element value * \brief Set CTL element value
* \param ctl CTL handle * \param ctl CTL handle
* \param control CTL element id/value pointer * \param obj Data of an element.
* \retval 0 on success * \retval 0 on success
* \retval >0 on success when value was changed * \retval >0 on success when value was changed
* \retval <0 a negative error code * \retval <0 a negative error code
@ -2295,8 +2295,8 @@ void snd_ctl_elem_info_set_index(snd_ctl_elem_info_t *obj, unsigned int val)
} }
/** /**
* \brief get size of #snd_ctl_elem_value_t * \brief Get size of data structure for an element.
* \return size in bytes * \return Size in bytes.
*/ */
size_t snd_ctl_elem_value_sizeof() size_t snd_ctl_elem_value_sizeof()
{ {
@ -2304,9 +2304,9 @@ size_t snd_ctl_elem_value_sizeof()
} }
/** /**
* \brief allocate an invalid #snd_ctl_elem_value_t using standard malloc * \brief Allocate an invalid #snd_ctl_elem_value_t using standard malloc(3).
* \param ptr returned pointer * \param ptr Returned pointer for data of an element.
* \return 0 on success otherwise negative error code * \return 0 on success otherwise negative error code.
*/ */
int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr) int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
{ {
@ -2318,8 +2318,8 @@ int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr)
} }
/** /**
* \brief frees a previously allocated #snd_ctl_elem_value_t * \brief Frees a previously allocated data of an element.
* \param obj pointer to object to free * \param obj Data of an element.
*/ */
void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj) void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
{ {
@ -2327,8 +2327,8 @@ void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief clear given #snd_ctl_elem_value_t object * \brief Clear given data of an element.
* \param obj pointer to object to clear * \param obj Data of an element.
*/ */
void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj) void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj)
{ {
@ -2336,32 +2336,34 @@ void snd_ctl_elem_value_clear(snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief copy one #snd_ctl_elem_value_t to another * \brief Copy two data of elements.
* \param dst pointer to destination * \param dst Pointer to destination.
* \param src pointer to source * \param src Pointer to source.
*/ */
void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst, const snd_ctl_elem_value_t *src) void snd_ctl_elem_value_copy(snd_ctl_elem_value_t *dst,
const snd_ctl_elem_value_t *src)
{ {
assert(dst && src); assert(dst && src);
*dst = *src; *dst = *src;
} }
/** /**
* \brief compare one #snd_ctl_elem_value_t to another * \brief Compare one data of an element to the other.
* \param left pointer to first value * \param left Pointer to first data.
* \param right pointer to second value * \param right Pointer to second data.
* \return 0 on match, less than or greater than otherwise, see memcmp * \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, const snd_ctl_elem_value_t *right) int snd_ctl_elem_value_compare(snd_ctl_elem_value_t *left,
const snd_ctl_elem_value_t *right)
{ {
assert(left && right); assert(left && right);
return memcmp(left, right, sizeof(*left)); return memcmp(left, right, sizeof(*left));
} }
/** /**
* \brief Get CTL element identifier of a CTL element id/value * \brief Get element identifier from given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param ptr Pointer to returned CTL element identifier * \param ptr Pointer for element identifier.
*/ */
void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr) void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_t *ptr)
{ {
@ -2370,9 +2372,9 @@ void snd_ctl_elem_value_get_id(const snd_ctl_elem_value_t *obj, snd_ctl_elem_id_
} }
/** /**
* \brief Get element numeric identifier of a CTL element id/value * \brief Get element numeric identifier from given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \return element numeric identifier * \return Element numeric identifier.
*/ */
unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj) unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj)
{ {
@ -2381,9 +2383,10 @@ unsigned int snd_ctl_elem_value_get_numid(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Get interface part of CTL element identifier of a CTL element id/value * \brief Get interface part of element identifier from given data of an
* \param obj CTL element id/value * element.
* \return interface part of element identifier * \param obj Data of an element.
* \return Interface part of element identifier.
*/ */
snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj) snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t *obj)
{ {
@ -2392,9 +2395,9 @@ snd_ctl_elem_iface_t snd_ctl_elem_value_get_interface(const snd_ctl_elem_value_t
} }
/** /**
* \brief Get device part of CTL element identifier of a CTL element id/value * \brief Get device part of element identifier from given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \return device part of element identifier * \return Device part of element identifier.
*/ */
unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj) unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj)
{ {
@ -2403,9 +2406,10 @@ unsigned int snd_ctl_elem_value_get_device(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Get subdevice part of CTL element identifier of a CTL element id/value * \brief Get subdevice part of element identifier from given data of an
* \param obj CTL element id/value * element.
* \return subdevice part of element identifier * \param obj Data of an element.
* \return Subdevice part of element identifier.
*/ */
unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj) unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj)
{ {
@ -2414,9 +2418,9 @@ unsigned int snd_ctl_elem_value_get_subdevice(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Get name part of CTL element identifier of a CTL element id/value * \brief Get name part of element identifier from given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \return name part of element identifier * \return Name part of element identifier.
*/ */
const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj) const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj)
{ {
@ -2425,9 +2429,9 @@ const char *snd_ctl_elem_value_get_name(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Get index part of CTL element identifier of a CTL element id/value * \brief Get index part of element identifier from given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \return index part of element identifier * \return Index part of element identifier.
*/ */
unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj) unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj)
{ {
@ -2436,9 +2440,9 @@ unsigned int snd_ctl_elem_value_get_index(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Set CTL element identifier of a CTL element id/value * \brief Set element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param ptr CTL element identifier * \param ptr Pointer to an element identifier.
*/ */
void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr) void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_t *ptr)
{ {
@ -2447,9 +2451,9 @@ void snd_ctl_elem_value_set_id(snd_ctl_elem_value_t *obj, const snd_ctl_elem_id_
} }
/** /**
* \brief Set element numeric identifier of a CTL element id/value * \brief Set numeric identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val element numeric identifier * \param val Value for numeric identifier.
*/ */
void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val) void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val)
{ {
@ -2458,9 +2462,9 @@ void snd_ctl_elem_value_set_numid(snd_ctl_elem_value_t *obj, unsigned int val)
} }
/** /**
* \brief Set interface part of CTL element identifier of a CTL element id/value * \brief Set interface part of element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val interface part of element identifier * \param val Value for interface part of element identifier.
*/ */
void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val) void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_iface_t val)
{ {
@ -2469,9 +2473,9 @@ void snd_ctl_elem_value_set_interface(snd_ctl_elem_value_t *obj, snd_ctl_elem_if
} }
/** /**
* \brief Set device part of CTL element identifier of a CTL element id/value * \brief Set device part of element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val device part of element identifier * \param val Value for device part of element identifier.
*/ */
void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val) void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val)
{ {
@ -2480,9 +2484,9 @@ void snd_ctl_elem_value_set_device(snd_ctl_elem_value_t *obj, unsigned int val)
} }
/** /**
* \brief Set subdevice part of CTL element identifier of a CTL element id/value * \brief Set subdevice part of element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val subdevice part of element identifier * \param val Value for subdevice part of element identifier.
*/ */
void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val) void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int val)
{ {
@ -2491,9 +2495,9 @@ void snd_ctl_elem_value_set_subdevice(snd_ctl_elem_value_t *obj, unsigned int va
} }
/** /**
* \brief Set name part of CTL element identifier of a CTL element id/value * \brief Set name part of element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val name part of element identifier * \param val Value for name part of element identifier,
*/ */
void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val) void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val)
{ {
@ -2502,9 +2506,9 @@ void snd_ctl_elem_value_set_name(snd_ctl_elem_value_t *obj, const char *val)
} }
/** /**
* \brief Set index part of CTL element identifier of a CTL element id/value * \brief Set index part of element identifier to given data of an element.
* \param obj CTL element id/value * \param obj Data of an element.
* \param val index part of element identifier * \param val Value for index part of element identifier.
*/ */
void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val) void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val)
{ {
@ -2513,10 +2517,11 @@ void snd_ctl_elem_value_set_index(snd_ctl_elem_value_t *obj, unsigned int val)
} }
/** /**
* \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_BOOLEAN CTL element id/value * \brief Get value of a specified member from given data as an element of
* \param obj CTL element id/value * boolean type.
* \param idx Entry index * \param obj Data of an element.
* \return value for the entry * \param idx Index of member in the element.
* \return Value for the member.
*/ */
int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx) int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int idx)
{ {
@ -2526,10 +2531,11 @@ int snd_ctl_elem_value_get_boolean(const snd_ctl_elem_value_t *obj, unsigned int
} }
/** /**
* \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/value * \brief Get value of a specified member from given data as an element of
* \param obj CTL element id/value * integer type.
* \param idx Entry index * \param obj Data of an element.
* \return value for the entry * \param idx Index of member in the element.
* \return Value for the member.
*/ */
long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx) long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned int idx)
{ {
@ -2539,10 +2545,11 @@ long snd_ctl_elem_value_get_integer(const snd_ctl_elem_value_t *obj, unsigned in
} }
/** /**
* \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/value * \brief Get value of a specified member from given data as an element of
* \param obj CTL element id/value * integer64 type.
* \param idx Entry index * \param obj Data of an element.
* \return value for the entry * \param idx Index of member in the element.
* \return Value for the member.
*/ */
long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx) long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsigned int idx)
{ {
@ -2552,10 +2559,11 @@ long long snd_ctl_elem_value_get_integer64(const snd_ctl_elem_value_t *obj, unsi
} }
/** /**
* \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/value * \brief Get value of a specified member from given data as an element of
* \param obj CTL element id/value * enumerated type.
* \param idx Entry index * \param obj Data of an element.
* \return value for the entry * \param idx Index of member in the element.
* \return Value for the member. This is an index of name set in the element.
*/ */
unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx) unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj, unsigned int idx)
{ {
@ -2565,10 +2573,11 @@ unsigned int snd_ctl_elem_value_get_enumerated(const snd_ctl_elem_value_t *obj,
} }
/** /**
* \brief Get value for an entry of a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value * \brief Get value of a specified member from given data as an element of
* \param obj CTL element id/value * bytes type.
* \param idx Entry index * \param obj Data of an element.
* \return value for the entry * \param idx Index of member in the element.
* \return Value for the member.
*/ */
unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx) unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsigned int idx)
{ {
@ -2578,10 +2587,11 @@ unsigned char snd_ctl_elem_value_get_byte(const snd_ctl_elem_value_t *obj, unsig
} }
/** /**
* \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_BOOLEAN CTL element id/value * \brief Set value of a specified member to given data as an element of
* \param obj CTL element id/value * boolean type.
* \param idx Entry index * \param obj Data of an element.
* \param val value for the entry * \param idx Index of member in the element.
* \param val Value for the member.
*/ */
void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val) void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
{ {
@ -2591,10 +2601,11 @@ void snd_ctl_elem_value_set_boolean(snd_ctl_elem_value_t *obj, unsigned int idx,
} }
/** /**
* \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER CTL element id/value * \brief Set value of a specified member to given data as an element of
* \param obj CTL element id/value * integer type.
* \param idx Entry index * \param obj Data of an element.
* \param val value for the entry * \param idx Index of member in the element.
* \param val Value for the member.
*/ */
void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val) void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx, long val)
{ {
@ -2604,10 +2615,11 @@ void snd_ctl_elem_value_set_integer(snd_ctl_elem_value_t *obj, unsigned int idx,
} }
/** /**
* \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_INTEGER64 CTL element id/value * \brief Set value of a specified member to given data as an element of
* \param obj CTL element id/value * integer64 type.
* \param idx Entry index * \param obj Data of an element.
* \param val value for the entry * \param idx Index of member in the element.
* \param val Value for the member.
*/ */
void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val) void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int idx, long long val)
{ {
@ -2617,10 +2629,11 @@ void snd_ctl_elem_value_set_integer64(snd_ctl_elem_value_t *obj, unsigned int id
} }
/** /**
* \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_ENUMERATED CTL element id/value * \brief Set value of a specified member to given data as an element of
* \param obj CTL element id/value * enumerated type.
* \param idx Entry index * \param obj Data of an element.
* \param val value for the entry * \param idx Index of member in the element.
* \param val Value for the member.
*/ */
void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val) void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned int val)
{ {
@ -2630,10 +2643,11 @@ void snd_ctl_elem_value_set_enumerated(snd_ctl_elem_value_t *obj, unsigned int i
} }
/** /**
* \brief Set value for an entry of a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value * \brief Set value for a specified member to given data as an element of byte
* \param obj CTL element id/value * type.
* \param idx Entry index * \param obj Data of an element.
* \param val value for the entry * \param idx Index of member in the element.
* \param val Value for the member.
*/ */
void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val) void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, unsigned char val)
{ {
@ -2643,10 +2657,10 @@ void snd_ctl_elem_value_set_byte(snd_ctl_elem_value_t *obj, unsigned int idx, un
} }
/** /**
* \brief Set CTL element #SND_CTL_ELEM_TYPE_BYTES value * \brief Set values to given data as an element of bytes type.
* \param obj CTL handle * \param obj Data of an element.
* \param data Bytes value * \param data Pointer for byte array.
* \param size Size in bytes * \param size The number of bytes included in the memory block.
*/ */
void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size) void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size)
{ {
@ -2656,9 +2670,9 @@ void snd_ctl_elem_set_bytes(snd_ctl_elem_value_t *obj, void *data, size_t size)
} }
/** /**
* \brief Get value for a #SND_CTL_ELEM_TYPE_BYTES CTL element id/value * \brief Get memory block from given data as an element of bytes type.
* \param obj CTL element id/value * \param obj Data of an element.
* \return Pointer to CTL element value * \return Pointer for byte array.
*/ */
const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj) const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
{ {
@ -2667,9 +2681,10 @@ const void * snd_ctl_elem_value_get_bytes(const snd_ctl_elem_value_t *obj)
} }
/** /**
* \brief Get value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value * \brief Get value from given data to given pointer as an element of IEC958
* \param obj CTL element id/value * type.
* \param ptr Pointer to returned CTL element value * \param obj Data of an element.
* \param ptr Pointer to IEC958 data.
*/ */
void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr) void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec958_t *ptr)
{ {
@ -2678,9 +2693,10 @@ void snd_ctl_elem_value_get_iec958(const snd_ctl_elem_value_t *obj, snd_aes_iec9
} }
/** /**
* \brief Set value for a #SND_CTL_ELEM_TYPE_IEC958 CTL element id/value * \brief Set value from given pointer to given data as an element of IEC958
* \param obj CTL element id/value * type.
* \param ptr Pointer to CTL element value * \param obj Data of an element.
* \param ptr Pointer to IEC958 data.
*/ */
void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr) void snd_ctl_elem_value_set_iec958(snd_ctl_elem_value_t *obj, const snd_aes_iec958_t *ptr)
{ {