control: Add documentation for snd_ctl_card_* and friends.
PATCH 1/2 control: Add documentation for snd_ctl_card_* and friends.
In this patch series, I added a description about control interface handling and how control interfaces are identified.
In addition, I added/improved Doxygen documentation for the snd_ctl_card_info_t type and related corresponding functions, e.g. snd_ctl_card_info(). I also documented other card-related like snd_card_next().
Along the way I did minor documentation improvements.
Signed-off-by Tanjeff-N. Moos <[email protected]>
--- include/control.h | 40 +++++++++- src/control/cards.c | 56 +++++++++----- src/control/control.c | 175 +++++++++++++++++++++++++++++++----------- 3 files changed, 202 insertions(+), 69 deletions(-)
include/control.h +37 -3
@@ -50,7 +50,32 @@ typedef struct snd_aes_iec958 {unsigned char dig_subframe[4 ];/**< AES/IEC958 subframe bits */ } snd_aes_iec958_t; -/** CTL card info container */ +/** \brief CTL card info container. +* +* This type contains meta information about a sound card, such as the index, +* name, longname, etc. +* +* \par Memory management +* +* Before using a snd_ctl_card_info_t object, it must be allocated using +* snd_ctl_card_info_alloca() or snd_ctl_card_info_malloc(). When using the +* latter, it must be freed again using snd_ctl_card_info_free(). +* +* A card info object can be zeroed out using snd_ctl_card_info_clear(). +* +* A card info object can be copied to another one using +* snd_ctl_card_info_copy(). +* +* \par Obtaining the Information +* +* To obtain the card information, it must first be opened using +* snd_ctl_open(), and a snd_ctl_card_info_t container must be +* allocated. Then, the information can be read using +* snd_ctl_card_info_get_card(). +* +* Thereafter, the card properties can be read using the +* snd_ctl_card_info_get_*() functions. +*/ typedef struct _snd_ctl_card_info snd_ctl_card_info_t ;/** CTL element identifier container */
@@ -438,11 +463,20 @@ void snd_ctl_elem_id_set_name(snd_ctl_elem_id_t *obj, const char *val);void snd_ctl_elem_id_set_index (snd_ctl_elem_id_t *obj,unsigned int val);size_t snd_ctl_card_info_sizeof (void ); +/** \hideinitializer -* \brief allocate an invalid #snd_ctl_card_info_t using standard alloca -* \param ptr returned pointer +* \brief Allocate an invalid #snd_ctl_card_info_t on the stack. +* +* Allocate space for a card info object on the stack. The allocated +* memory need not be freed, because it is on the stack. +* +* See snd_ctl_card_info_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_card_info_alloca (ptr) __snd_alloca(ptr, snd_ctl_card_info) +int snd_ctl_card_info_malloc (snd_ctl_card_info_t **ptr);void snd_ctl_card_info_free (snd_ctl_card_info_t *obj);void snd_ctl_card_info_clear (snd_ctl_card_info_t *obj);
src/control/cards.c +36 -20
88 lines not on this page · raw message
src/control/control.c +129 -46
291 lines not on this page · raw message
Signature · 1 line
2.17.1
PATCH 2/2 control: Minor documentation fixes.
Signed-off-by Tanjeff-N. Moos <[email protected]>
--- include/control.h | 9 +++++++-- src/control/cards.c | 5 ++++- src/control/control.c | 2 +- 3 files changed, 12 insertions(+), 4 deletions(-)
include/control.h +7 -2
@@ -155,7 +155,7 @@ 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.
@@ -167,6 +167,11 @@ typedef struct _snd_ctl_elem_info snd_ctl_elem_info_t;* using the latter, it must be freed again using * snd_ctl_elem_value_free(). * +* A value object can be zeroed out using snd_ctl_elem_value_clear(). +* +* A value object can be copied to another one using +* snd_ctl_elem_value_copy(). +* * \par Identifier * * Then, the ID must be filled. It is sufficient to fill only the
@@ -614,7 +619,7 @@ size_t snd_ctl_elem_value_sizeof(void);* \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. +* memory need not be freed, because it is on the stack. * * See snd_ctl_elem_value_t for details. *
src/control/cards.c +4 -1
@@ -147,6 +147,7 @@ int snd_card_get_index(const char *string)return -EINVAL ;if ((isdigit (*string) && *(string +1 ) ==0 ) || (isdigit (*string) &&isdigit (*(string +1 )) && *(string +2 ) ==0 )) { +/* We got an index */ if (sscanf (string,"%i" , &card) !=1 )return -EINVAL ;if (card <0 || card >=SND_MAX_CARDS )
@@ -156,8 +157,10 @@ int snd_card_get_index(const char *string)return card;return err; } -if (string[0 ] =='/' )/* device name */ +if (string[0 ] =='/' ) +/* We got a device name */ return snd_card_load2 (string); +/* We got in ID */ for (card =0 ; card <SND_MAX_CARDS ; card++) {#ifdef SUPPORT_ALOAD if (!snd_card_load (card))
src/control/control.c +1 -1
@@ -2985,7 +2985,7 @@ size_t snd_ctl_elem_value_sizeof()/** * \brief Allocate an invalid #snd_ctl_elem_value_t on the heap. * -* Allocate space for a value object on the head. The allocated memory +* Allocate space for a value object on the heap. The allocated memory * must be freed using snd_ctl_elem_value_free(). * * See snd_ctl_elem_value_t for details.
Signature · 1 line
2.17.1