From 78af661d60940d6a5119ecffdb7c91f1d6c60ce4 Mon Sep 17 00:00:00 2001 From: Abramo Bagnara Date: Thu, 29 Mar 2001 09:44:29 +0000 Subject: [PATCH] More documentation --- include/control.h | 21 ++++++++++++++++++ include/control_m4.h | 24 ++++++++++++++++++++ include/error.h | 9 ++++++++ include/pcm.h | 28 +++++++++++++++++------ include/rawmidi.h | 53 ++++++++++++++++++++++++++------------------ 5 files changed, 107 insertions(+), 28 deletions(-) diff --git a/include/control.h b/include/control.h index e3b311aa..abb81475 100644 --- a/include/control.h +++ b/include/control.h @@ -241,19 +241,40 @@ void snd_ctl_elem_list_free_space(snd_ctl_elem_list_t *obj); * Highlevel API for controls */ +/** HCTL element handle */ typedef struct _snd_hctl_elem snd_hctl_elem_t; +/** HCTL handle */ typedef struct _snd_hctl snd_hctl_t; #ifdef __cplusplus extern "C" { #endif +/** + * \brief Compare function for sorting HCTL elements + * \param e1 First element + * \param e2 Second element + * \return -1 if e1 < e2, 0 if e1 == e2, 1 if e1 > e2 + */ typedef int (*snd_hctl_compare_t)(const snd_hctl_elem_t *e1, const snd_hctl_elem_t *e2); +/** + * \brief HCTL callback function + * \param hctl HCTL handle + * \param mask event mask + * \param elem related HCTL element (if any) + * \return 0 on success otherwise a negative error code + */ typedef int (*snd_hctl_callback_t)(snd_hctl_t *hctl, unsigned int mask, snd_hctl_elem_t *elem); +/** + * \brief HCTL element callback function + * \param elem HCTL element + * \param mask event mask + * \return 0 on success otherwise a negative error code + */ typedef int (*snd_hctl_elem_callback_t)(snd_hctl_elem_t *elem, unsigned int mask); diff --git a/include/control_m4.h b/include/control_m4.h index 1023bc2d..9804a7c2 100644 --- a/include/control_m4.h +++ b/include/control_m4.h @@ -3,6 +3,10 @@ extern "C" { #endif size_t snd_ctl_elem_id_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_elem_id_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_elem_id_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_id_t *) alloca(snd_ctl_elem_id_sizeof()); memset(*ptr, 0, snd_ctl_elem_id_sizeof()); } while (0) int snd_ctl_elem_id_malloc(snd_ctl_elem_id_t **ptr); void snd_ctl_elem_id_free(snd_ctl_elem_id_t *obj); @@ -33,6 +37,10 @@ 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(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_card_info_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_card_info_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_card_info_t *) alloca(snd_ctl_card_info_sizeof()); memset(*ptr, 0, snd_ctl_card_info_sizeof()); } while (0) int snd_ctl_card_info_malloc(snd_ctl_card_info_t **ptr); void snd_ctl_card_info_free(snd_ctl_card_info_t *obj); @@ -55,6 +63,10 @@ const char *snd_ctl_card_info_get_mixerid(const snd_ctl_card_info_t *obj); const char *snd_ctl_card_info_get_mixername(const snd_ctl_card_info_t *obj); size_t snd_ctl_event_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_event_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_event_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_event_t *) alloca(snd_ctl_event_sizeof()); memset(*ptr, 0, snd_ctl_event_sizeof()); } while (0) int snd_ctl_event_malloc(snd_ctl_event_t **ptr); void snd_ctl_event_free(snd_ctl_event_t *obj); @@ -63,6 +75,10 @@ void snd_ctl_event_copy(snd_ctl_event_t *dst, const snd_ctl_event_t *src); snd_ctl_event_type_t snd_ctl_event_get_type(const snd_ctl_event_t *obj); size_t snd_ctl_elem_list_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_elem_list_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_elem_list_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_list_t *) alloca(snd_ctl_elem_list_sizeof()); memset(*ptr, 0, snd_ctl_elem_list_sizeof()); } while (0) int snd_ctl_elem_list_malloc(snd_ctl_elem_list_t **ptr); void snd_ctl_elem_list_free(snd_ctl_elem_list_t *obj); @@ -89,6 +105,10 @@ const char *snd_ctl_elem_list_get_name(const snd_ctl_elem_list_t *obj, unsigned unsigned int snd_ctl_elem_list_get_index(const snd_ctl_elem_list_t *obj, unsigned int idx); size_t snd_ctl_elem_info_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_elem_info_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_elem_info_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_info_t *) alloca(snd_ctl_elem_info_sizeof()); memset(*ptr, 0, snd_ctl_elem_info_sizeof()); } while (0) int snd_ctl_elem_info_malloc(snd_ctl_elem_info_t **ptr); void snd_ctl_elem_info_free(snd_ctl_elem_info_t *obj); @@ -151,6 +171,10 @@ void snd_ctl_elem_info_set_name(snd_ctl_elem_info_t *obj, const char *val); void snd_ctl_elem_info_set_index(snd_ctl_elem_info_t *obj, unsigned int val); size_t snd_ctl_elem_value_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_ctl_elem_value_t using standard alloca + * \param ptr returned pointer + */ #define snd_ctl_elem_value_alloca(ptr) do { assert(ptr); *ptr = (snd_ctl_elem_value_t *) alloca(snd_ctl_elem_value_sizeof()); memset(*ptr, 0, snd_ctl_elem_value_sizeof()); } while (0) int snd_ctl_elem_value_malloc(snd_ctl_elem_value_t **ptr); void snd_ctl_elem_value_free(snd_ctl_elem_value_t *obj); diff --git a/include/error.h b/include/error.h index d13046d4..0a03ac80 100644 --- a/include/error.h +++ b/include/error.h @@ -11,6 +11,15 @@ extern "C" { const char *snd_strerror(int errnum); +/** + * \brief Error handler + * \param file File name + * \param line Line number + * \param function Function name + * \param err errno value (or 0 if not relevant) + * \param fmt printf(3) format + * \param ... printf(3) arguments + */ typedef void (snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((weak, format (printf, 5, 6))) */; extern snd_lib_error_handler_t *snd_lib_error; extern int snd_lib_error_set_handler(snd_lib_error_handler_t *handler); diff --git a/include/pcm.h b/include/pcm.h index 04d15473..f339d92c 100644 --- a/include/pcm.h +++ b/include/pcm.h @@ -410,19 +410,33 @@ ssize_t snd_pcm_samples_to_bytes(snd_pcm_t *pcm, int samples); /** #SND_PCM_TYPE_METER scope functions */ typedef struct _snd_pcm_scope_ops { - /** Enable and prepare it using current params */ + /** \brief Enable and prepare it using current params + * \param scope scope handle + */ int (*enable)(snd_pcm_scope_t *scope); - /** Disable */ + /** \brief Disable + * \param scope scope handle + */ void (*disable)(snd_pcm_scope_t *scope); - /** PCM has been started */ + /** \brief PCM has been started + * \param scope scope handle + */ void (*start)(snd_pcm_scope_t *scope); - /** PCM has been stopped */ + /** \brief PCM has been stopped + * \param scope scope handle + */ void (*stop)(snd_pcm_scope_t *scope); - /** New frames are present */ + /** \brief New frames are present + * \param scope scope handle + */ void (*update)(snd_pcm_scope_t *scope); - /** Reset status */ + /** \brief Reset status + * \param scope scope handle + */ void (*reset)(snd_pcm_scope_t *scope); - /** PCM is closing */ + /** \brief PCM is closing + * \param scope scope handle + */ void (*close)(snd_pcm_scope_t *scope); } snd_pcm_scope_ops_t; diff --git a/include/rawmidi.h b/include/rawmidi.h index d7296e7d..7859dcaa 100644 --- a/include/rawmidi.h +++ b/include/rawmidi.h @@ -5,40 +5,39 @@ * * ****************************************************************************/ +/** RawMidi information container */ typedef struct _snd_rawmidi_info snd_rawmidi_info_t; +/** RawMidi settings container */ typedef struct _snd_rawmidi_params snd_rawmidi_params_t; +/** RawMidi status container */ typedef struct _snd_rawmidi_status snd_rawmidi_status_t; -#ifdef SND_ENUM_TYPECHECK -typedef struct __snd_rawmidi_stream *snd_rawmidi_stream_t; -#else -typedef enum sndrv_rawmidi_stream snd_rawmidi_stream_t; -#endif - -#define SND_RAWMIDI_STREAM_OUTPUT ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_OUTPUT) -#define SND_RAWMIDI_STREAM_INPUT ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_INPUT) -#define SND_RAWMIDI_STREAM_LAST ((snd_rawmidi_stream_t) SNDRV_RAWMIDI_STREAM_LAST) +/** RawMidi stream (direction) */ +typedef enum _snd_rawmidi_stream { + /** Output stream */ + SND_RAWMIDI_STREAM_OUTPUT = SNDRV_RAWMIDI_STREAM_OUTPUT, + /** Input stream */ + SND_RAWMIDI_STREAM_INPUT = SNDRV_RAWMIDI_STREAM_INPUT, + SND_RAWMIDI_STREAM_LAST = SNDRV_RAWMIDI_STREAM_LAST, +} snd_rawmidi_stream_t; +/** Append \hideinitializer */ #define SND_RAWMIDI_APPEND 1 +/** Non blocking mode \hideinitializer */ #define SND_RAWMIDI_NONBLOCK 2 +/** RawMidi handle */ typedef struct _snd_rawmidi snd_rawmidi_t; -enum _snd_rawmidi_type { +/** RawMidi type */ +typedef enum _snd_rawmidi_type { + /** Kernel level RawMidi */ SND_RAWMIDI_TYPE_HW, + /** Shared memory client RawMidi (not yet implemented) */ SND_RAWMIDI_TYPE_SHM, + /** INET client RawMidi (not yet implemented) */ SND_RAWMIDI_TYPE_INET, -}; - -#ifdef SND_ENUM_TYPECHECK -typedef struct __snd_rawmidi_type *snd_rawmidi_type_t; -#else -typedef enum _snd_rawmidi_type snd_rawmidi_type_t; -#endif - -#define SND_RAWMIDI_TYPE_HW ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_HW) -#define SND_RAWMIDI_TYPE_SHM ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_SHM) -#define SND_RAWMIDI_TYPE_INET ((snd_rawmidi_type_t) SND_RAWMIDI_TYPE_INET) +} snd_rawmidi_type_t; #ifdef __cplusplus extern "C" { @@ -51,6 +50,10 @@ int snd_rawmidi_poll_descriptors_count(snd_rawmidi_t *rmidi); int snd_rawmidi_poll_descriptors(snd_rawmidi_t *rmidi, struct pollfd *pfds, unsigned int space); int snd_rawmidi_nonblock(snd_rawmidi_t *rmidi, int nonblock); size_t snd_rawmidi_info_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_rawmidi_info_t using standard alloca + * \param ptr returned pointer + */ #define snd_rawmidi_info_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_info_t *) alloca(snd_rawmidi_info_sizeof()); memset(*ptr, 0, snd_rawmidi_info_sizeof()); } while (0) int snd_rawmidi_info_malloc(snd_rawmidi_info_t **ptr); void snd_rawmidi_info_free(snd_rawmidi_info_t *obj); @@ -70,6 +73,10 @@ void snd_rawmidi_info_set_subdevice(snd_rawmidi_info_t *obj, unsigned int val); void snd_rawmidi_info_set_stream(snd_rawmidi_info_t *obj, snd_rawmidi_stream_t val); int snd_rawmidi_info(snd_rawmidi_t *rmidi, snd_rawmidi_info_t * info); size_t snd_rawmidi_params_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_rawmidi_params_t using standard alloca + * \param ptr returned pointer + */ #define snd_rawmidi_params_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_params_t *) alloca(snd_rawmidi_params_sizeof()); memset(*ptr, 0, snd_rawmidi_params_sizeof()); } while (0) int snd_rawmidi_params_malloc(snd_rawmidi_params_t **ptr); void snd_rawmidi_params_free(snd_rawmidi_params_t *obj); @@ -83,6 +90,10 @@ int snd_rawmidi_params_get_no_active_sensing(const snd_rawmidi_params_t *params) int snd_rawmidi_params(snd_rawmidi_t *rmidi, snd_rawmidi_params_t * params); int snd_rawmidi_params_current(snd_rawmidi_t *rmidi, snd_rawmidi_params_t *params); size_t snd_rawmidi_status_sizeof(); +/** \hideinitializer + * \brief allocate an invalid #snd_rawmidi_status_t using standard alloca + * \param ptr returned pointer + */ #define snd_rawmidi_status_alloca(ptr) do { assert(ptr); *ptr = (snd_rawmidi_status_t *) alloca(snd_rawmidi_status_sizeof()); memset(*ptr, 0, snd_rawmidi_status_sizeof()); } while (0) int snd_rawmidi_status_malloc(snd_rawmidi_status_t **ptr); void snd_rawmidi_status_free(snd_rawmidi_status_t *obj); -- 2.47.1