From 63d708a3447ce7b5d92035ddcd5c435db21e9f61 Mon Sep 17 00:00:00 2001 From: Jaroslav Kysela Date: Tue, 23 Jul 2002 19:51:16 +0000 Subject: [PATCH] Documentation update by Clement Ladish --- doc/index.doxygen | 32 +- include/asoundef.h | 62 ++-- include/conf.h | 57 +-- include/conv.h | 22 +- include/error.h | 41 ++- include/global.h | 32 +- include/input.h | 32 +- include/output.h | 32 +- src/async.c | 64 ++-- src/conf.c | 845 +++++++++++++++++++++++++-------------------- src/confmisc.c | 219 ++++++------ src/dlmisc.c | 50 +-- src/error.c | 23 +- src/input.c | 83 +++-- src/output.c | 85 +++-- 15 files changed, 965 insertions(+), 714 deletions(-) diff --git a/doc/index.doxygen b/doc/index.doxygen index c0645f04..9b2c6a50 100644 --- a/doc/index.doxygen +++ b/doc/index.doxygen @@ -7,36 +7,36 @@

Preface

The Advanced Linux Sound Architecture (\e ALSA) comes with a kernel -API & library API. This document describes the library API and how +API and a library API. This document describes the library API and how it interfaces with the kernel API.

Documentation License

This documentation is free; you can redistribute it without -any restrictions. The modification or derived work must retain -copyright and list all authors.

+any restrictions. Modifications or derived work must retain +the copyright and list all authors.

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

API usage

-

Application programmers should use the library API rather than -kernel API. The library offers 100% of the functionally of the kernel API, -but add major improvements in usability, making the application code simpler -and better looking. In addition, some of the some fixes/compatibility code +

Application programmers should use the library API rather than the +kernel API. The library offers 100% of the functionality of the kernel API, +but adds major improvements in usability, making the application code simpler +and better looking. In addition, future fixes or compatibility code may be placed in the library code instead of the kernel driver.

API links

Configuration

@@ -44,8 +44,8 @@ may be placed in the library code instead of the kernel driver.

*/ diff --git a/include/asoundef.h b/include/asoundef.h index 5772735b..97991fda 100644 --- a/include/asoundef.h +++ b/include/asoundef.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Definitions of constants for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -33,8 +33,8 @@ extern "C" { #endif /** - * \defgroup Digital_Audio_Interface Constants For Digital Audio Interface - * AES/IEC958 channel status bits + * \defgroup Digital_Audio_Interface Constants for Digital Audio Interfaces + * AES/IEC958 channel status bits. * \{ */ @@ -42,7 +42,7 @@ extern "C" { #define IEC958_AES0_NONAUDIO (1<<1) /**< 0 = audio, 1 = non-audio */ #define IEC958_AES0_PRO_EMPHASIS (7<<2) /**< mask - emphasis */ #define IEC958_AES0_PRO_EMPHASIS_NOTID (0<<2) /**< emphasis not indicated */ -#define IEC958_AES0_PRO_EMPHASIS_NONE (1<<2) /**< none emphasis */ +#define IEC958_AES0_PRO_EMPHASIS_NONE (1<<2) /**< no emphasis */ #define IEC958_AES0_PRO_EMPHASIS_5015 (3<<2) /**< 50/15us emphasis */ #define IEC958_AES0_PRO_EMPHASIS_CCITT (7<<2) /**< CCITT J.17 emphasis */ #define IEC958_AES0_PRO_FREQ_UNLOCKED (1<<5) /**< source sample frequency: 0 = locked, 1 = unlocked */ @@ -53,18 +53,18 @@ extern "C" { #define IEC958_AES0_PRO_FS_32000 (3<<6) /**< 32kHz */ #define IEC958_AES0_CON_NOT_COPYRIGHT (1<<2) /**< 0 = copyright, 1 = not copyright */ #define IEC958_AES0_CON_EMPHASIS (7<<3) /**< mask - emphasis */ -#define IEC958_AES0_CON_EMPHASIS_NONE (0<<3) /**< none emphasis */ +#define IEC958_AES0_CON_EMPHASIS_NONE (0<<3) /**< no emphasis */ #define IEC958_AES0_CON_EMPHASIS_5015 (1<<3) /**< 50/15us emphasis */ #define IEC958_AES0_CON_MODE (3<<6) /**< mask - mode */ #define IEC958_AES1_PRO_MODE (15<<0) /**< mask - channel mode */ -#define IEC958_AES1_PRO_MODE_NOTID (0<<0) /**< not indicated */ +#define IEC958_AES1_PRO_MODE_NOTID (0<<0) /**< mode not indicated */ #define IEC958_AES1_PRO_MODE_STEREOPHONIC (2<<0) /**< stereophonic - ch A is left */ #define IEC958_AES1_PRO_MODE_SINGLE (4<<0) /**< single channel */ #define IEC958_AES1_PRO_MODE_TWO (8<<0) /**< two channels */ #define IEC958_AES1_PRO_MODE_PRIMARY (12<<0) /**< primary/secondary */ #define IEC958_AES1_PRO_MODE_BYTE3 (15<<0) /**< vector to byte 3 */ #define IEC958_AES1_PRO_USERBITS (15<<4) /**< mask - user bits */ -#define IEC958_AES1_PRO_USERBITS_NOTID (0<<4) /**< not indicated */ +#define IEC958_AES1_PRO_USERBITS_NOTID (0<<4) /**< user bits not indicated */ #define IEC958_AES1_PRO_USERBITS_192 (8<<4) /**< 192-bit structure */ #define IEC958_AES1_PRO_USERBITS_UDEF (12<<4) /**< user defined application */ #define IEC958_AES1_CON_CATEGORY 0x7f /**< consumer category */ @@ -104,15 +104,15 @@ extern "C" { #define IEC958_AES2_PRO_SBITS_24 (4<<0) /**< 24-bit - main audio */ #define IEC958_AES2_PRO_SBITS_UDEF (6<<0) /**< user defined application */ #define IEC958_AES2_PRO_WORDLEN (7<<3) /**< mask - source word length */ -#define IEC958_AES2_PRO_WORDLEN_NOTID (0<<3) /**< not indicated */ +#define IEC958_AES2_PRO_WORDLEN_NOTID (0<<3) /**< source word length not indicated */ #define IEC958_AES2_PRO_WORDLEN_22_18 (2<<3) /**< 22-bit or 18-bit */ #define IEC958_AES2_PRO_WORDLEN_23_19 (4<<3) /**< 23-bit or 19-bit */ #define IEC958_AES2_PRO_WORDLEN_24_20 (5<<3) /**< 24-bit or 20-bit */ #define IEC958_AES2_PRO_WORDLEN_20_16 (6<<3) /**< 20-bit or 16-bit */ #define IEC958_AES2_CON_SOURCE (15<<0) /**< mask - source number */ -#define IEC958_AES2_CON_SOURCE_UNSPEC (0<<0) /**< unspecified */ +#define IEC958_AES2_CON_SOURCE_UNSPEC (0<<0) /**< source number unspecified */ #define IEC958_AES2_CON_CHANNEL (15<<4) /**< mask - channel number */ -#define IEC958_AES2_CON_CHANNEL_UNSPEC (0<<4) /**< unspecified */ +#define IEC958_AES2_CON_CHANNEL_UNSPEC (0<<4) /**< channel number unspecified */ #define IEC958_AES3_CON_FS (15<<0) /**< mask - sample frequency */ #define IEC958_AES3_CON_FS_44100 (0<<0) /**< 44.1kHz */ #define IEC958_AES3_CON_FS_48000 (2<<0) /**< 48kHz */ @@ -125,32 +125,32 @@ extern "C" { /** \} */ /** - * \defgroup MIDI_Interface Constants For MIDI v1.0 Interface - * Constants for MIDI v1.0 interface + * \defgroup MIDI_Interface Constants for MIDI v1.0 + * Constants for MIDI v1.0. * \{ */ -#define MIDI_CHANNELS 16 /**< number of channels */ -#define MIDI_GM_DRUM_CHANNEL (10-1) /**< channel number for GM drum */ +#define MIDI_CHANNELS 16 /**< Number of channels per port/cable. */ +#define MIDI_GM_DRUM_CHANNEL (10-1) /**< Channel number for GM drums. */ /** * \defgroup MIDI_Commands MIDI Commands - * MIDI Commands + * MIDI command codes. * \{ */ -#define MIDI_CMD_NOTE_OFF 0x80 /**< note-off */ -#define MIDI_CMD_NOTE_ON 0x90 /**< note-on */ -#define MIDI_CMD_NOTE_PRESSURE 0xa0 /**< key-pressure */ -#define MIDI_CMD_CONTROL 0xb0 /**< MIDI control */ +#define MIDI_CMD_NOTE_OFF 0x80 /**< note off */ +#define MIDI_CMD_NOTE_ON 0x90 /**< note on */ +#define MIDI_CMD_NOTE_PRESSURE 0xa0 /**< key pressure */ +#define MIDI_CMD_CONTROL 0xb0 /**< control change */ #define MIDI_CMD_PGM_CHANGE 0xc0 /**< program change */ -#define MIDI_CMD_CHANNEL_PRESSURE 0xd0 /**< channel-pressure */ -#define MIDI_CMD_BENDER 0xe0 /**< pitch-bender */ +#define MIDI_CMD_CHANNEL_PRESSURE 0xd0 /**< channel pressure */ +#define MIDI_CMD_BENDER 0xe0 /**< pitch bender */ #define MIDI_CMD_COMMON_SYSEX 0xf0 /**< sysex (system exclusive) begin */ #define MIDI_CMD_COMMON_MTC_QUARTER 0xf1 /**< MTC quarter frame */ #define MIDI_CMD_COMMON_SONG_POS 0xf2 /**< song position */ -#define MIDI_CMD_COMMON_SONG_SELECT 0xf3 /**< song selection */ +#define MIDI_CMD_COMMON_SONG_SELECT 0xf3 /**< song select */ #define MIDI_CMD_COMMON_TUNE_REQUEST 0xf6 /**< tune request */ #define MIDI_CMD_COMMON_SYSEX_END 0xf7 /**< end of sysex */ #define MIDI_CMD_COMMON_CLOCK 0xf8 /**< clock */ @@ -158,25 +158,25 @@ extern "C" { #define MIDI_CMD_COMMON_CONTINUE 0xfb /**< continue */ #define MIDI_CMD_COMMON_STOP 0xfc /**< stop */ #define MIDI_CMD_COMMON_SENSING 0xfe /**< active sensing */ -#define MIDI_CMD_COMMON_RESET 0xff /**< MIDI reset */ +#define MIDI_CMD_COMMON_RESET 0xff /**< reset */ /** \} */ /** * \defgroup MIDI_Controllers MIDI Controllers - * MIDI Controllers + * MIDI controller numbers. * \{ */ #define MIDI_CTL_MSB_BANK 0x00 /**< Bank selection */ -#define MIDI_CTL_MSB_MODWHEEL 0x01 /**< Modwheel */ +#define MIDI_CTL_MSB_MODWHEEL 0x01 /**< Modulation */ #define MIDI_CTL_MSB_BREATH 0x02 /**< Breath */ #define MIDI_CTL_MSB_FOOT 0x04 /**< Foot */ #define MIDI_CTL_MSB_PORTAMENTO_TIME 0x05 /**< Portamento time */ #define MIDI_CTL_MSB_DATA_ENTRY 0x06 /**< Data entry */ #define MIDI_CTL_MSB_MAIN_VOLUME 0x07 /**< Main volume */ #define MIDI_CTL_MSB_BALANCE 0x08 /**< Balance */ -#define MIDI_CTL_MSB_PAN 0x0a /**< Pan */ +#define MIDI_CTL_MSB_PAN 0x0a /**< Panpot */ #define MIDI_CTL_MSB_EXPRESSION 0x0b /**< Expression */ #define MIDI_CTL_MSB_EFFECT1 0x0c /**< Effect1 */ #define MIDI_CTL_MSB_EFFECT2 0x0d /**< Effect2 */ @@ -185,14 +185,14 @@ extern "C" { #define MIDI_CTL_MSB_GENERAL_PURPOSE3 0x12 /**< General purpose 3 */ #define MIDI_CTL_MSB_GENERAL_PURPOSE4 0x13 /**< General purpose 4 */ #define MIDI_CTL_LSB_BANK 0x20 /**< Bank selection */ -#define MIDI_CTL_LSB_MODWHEEL 0x21 /**< Modwheel */ +#define MIDI_CTL_LSB_MODWHEEL 0x21 /**< Modulation */ #define MIDI_CTL_LSB_BREATH 0x22 /**< Breath */ #define MIDI_CTL_LSB_FOOT 0x24 /**< Foot */ #define MIDI_CTL_LSB_PORTAMENTO_TIME 0x25 /**< Portamento time */ #define MIDI_CTL_LSB_DATA_ENTRY 0x26 /**< Data entry */ #define MIDI_CTL_LSB_MAIN_VOLUME 0x27 /**< Main volume */ #define MIDI_CTL_LSB_BALANCE 0x28 /**< Balance */ -#define MIDI_CTL_LSB_PAN 0x2a /**< Pan */ +#define MIDI_CTL_LSB_PAN 0x2a /**< Panpot */ #define MIDI_CTL_LSB_EXPRESSION 0x2b /**< Expression */ #define MIDI_CTL_LSB_EFFECT1 0x2c /**< Effect1 */ #define MIDI_CTL_LSB_EFFECT2 0x2d /**< Effect2 */ @@ -200,9 +200,9 @@ extern "C" { #define MIDI_CTL_LSB_GENERAL_PURPOSE2 0x31 /**< General purpose 2 */ #define MIDI_CTL_LSB_GENERAL_PURPOSE3 0x32 /**< General purpose 3 */ #define MIDI_CTL_LSB_GENERAL_PURPOSE4 0x33 /**< General purpose 4 */ -#define MIDI_CTL_SUSTAIN 0x40 /**< Sustain */ +#define MIDI_CTL_SUSTAIN 0x40 /**< Sustain pedal */ #define MIDI_CTL_PORTAMENTO 0x41 /**< Portamento */ -#define MIDI_CTL_SUSTENUTO 0x42 /**< Sustenuto */ +#define MIDI_CTL_SUSTENUTO 0x42 /**< Sostenuto */ #define MIDI_CTL_SOFT_PEDAL 0x43 /**< Soft pedal */ #define MIDI_CTL_LEGATO_FOOTSWITCH 0x44 /**< Legato foot switch */ #define MIDI_CTL_HOLD2 0x45 /**< Hold2 */ diff --git a/include/conf.h b/include/conf.h index 02e883a9..e55385e7 100644 --- a/include/conf.h +++ b/include/conf.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Application interface library for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -34,36 +34,52 @@ extern "C" { /** * \defgroup Config Configuration Interface - * Configuration Interface + * The configuration functions and types allow you to read, enumerate, + * modify and write the contents of ALSA configuration files. * \{ */ -/** dlsym version for config evaluate callback */ +/** \brief \c dlsym version for the config evaluate callback. */ #define SND_CONFIG_DLSYM_VERSION_EVALUATE _dlsym_config_evaluate_001 -/** dlsym version for config hook callback */ +/** \brief \c dlsym version for the config hook callback. */ #define SND_CONFIG_DLSYM_VERSION_HOOK _dlsym_config_hook_001 -/** Config node type */ +/** Configuration node type. */ typedef enum _snd_config_type { - /** Integer number */ + /** Integer number. */ SND_CONFIG_TYPE_INTEGER, - /** 64 bit Integer number */ + /** 64 bit Integer number. */ SND_CONFIG_TYPE_INTEGER64, - /** Real number */ + /** Real number. */ SND_CONFIG_TYPE_REAL, - /** Character string */ + /** Character string. */ SND_CONFIG_TYPE_STRING, - /** Pointer - runtime only - cannot be saved */ + /** Pointer (runtime only, cannot be saved). */ SND_CONFIG_TYPE_POINTER, - /** Compound */ + /** Compound node. */ SND_CONFIG_TYPE_COMPOUND = 1024 } snd_config_type_t; -/** Config node handle */ +/** + * \brief Internal structure for a configuration node object. + * + * The ALSA library uses a pointer to this structure as a handle to a + * configuration node. Applications don't access its contents directly. + */ typedef struct _snd_config snd_config_t; -/** Config compound iterator */ +/** + * \brief Type for a configuration compound iterator. + * + * The ALSA library uses this pointer type as a handle to a configuration + * compound iterator. Applications don't directly access the contents of + * the structure pointed to by this type. + */ typedef struct _snd_config_iterator *snd_config_iterator_t; -/** Config private update structure */ +/** + * \brief Internal structure for a configuration private update object. + * + * The ALSA library uses this structure to save private update information. + */ typedef struct _snd_config_update snd_config_update_t; extern snd_config_t *snd_config; @@ -136,12 +152,13 @@ snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t itera snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node); snd_config_t *snd_config_iterator_entry(const snd_config_iterator_t iterator); -/** Helper for compound config node leaves traversal - * \param pos Current node iterator - * \param next Next node iterator - * \param node Compound config node +/** + * \brief Helper macro to iterate over the children of a compound node. + * \param pos Iterator variable for the current node. + * \param next Iterator variable for the next node. + * \param node Handle to the compound configuration node to iterate over. * - * This macro is designed to permit the removal of current node. + * This macro is designed to permit the removal of the current node. */ #define snd_config_for_each(pos, next, node) \ for (pos = snd_config_iterator_first(node), next = snd_config_iterator_next(pos); pos != snd_config_iterator_end(node); pos = next, next = snd_config_iterator_next(pos)) diff --git a/include/conv.h b/include/conv.h index cfb96c6c..a3268982 100644 --- a/include/conv.h +++ b/include/conv.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Application interface library for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -30,25 +30,25 @@ /** * \defgroup BConv Binary Value Conversion - * Binary Value Conversion + * Helper macros to convert binary values to/from a specific byte order. * \{ */ -/** convert 16-bit value from host to Little Endian byte order */ +/** Converts a 16-bit value from host to little endian byte order. */ #define snd_host_to_LE_16(val) __cpu_to_le16(val) -/** convert 16-bit value from Little Endian to host byte order */ +/** Converts a 16-bit value from little endian to host byte order. */ #define snd_LE_to_host_16(val) __le16_to_cpu(val) -/** convert 32-bit value from host to Little Endian byte order */ +/** Converts a 32-bit value from host to little endian byte order. */ #define snd_host_to_LE_32(val) __cpu_to_le32(val) -/** convert 32-bit value from Little Endian to host byte order */ +/** Converts a 32-bit value from little endian to host byte order. */ #define snd_LE_to_host_32(val) __le32_to_cpu(val) -/** convert 16-bit value from host to Big Endian byte order */ +/** Converts a 16-bit value from host to big endian byte order. */ #define snd_host_to_BE_16(val) __cpu_to_be16(val) -/** convert 16-bit value from Big Endian to host byte order */ +/** Converts a 16-bit value from big endian to host byte order. */ #define snd_BE_to_host_16(val) __be16_to_cpu(val) -/** convert 32-bit value from host to Big Endian byte order */ +/** Converts a 32-bit value from host to big endian byte order. */ #define snd_host_to_BE_32(val) __cpu_to_be32(val) -/** convert 32-bit value from Big Endian to host byte order */ +/** Converts a 32-bit value from big endian to host byte order. */ #define snd_BE_to_host_32(val) __be32_to_cpu(val) /** \} */ diff --git a/include/error.h b/include/error.h index c2100ea4..c1915bd1 100644 --- a/include/error.h +++ b/include/error.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Application interface library for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -34,34 +34,37 @@ extern "C" { /** * \defgroup Error Error handling - * Error handling + * Error handling macros and functions. * \{ */ -#define SND_ERROR_BEGIN 500000 /**< begin boundary of sound error codes */ -#define SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0) /**< protocol is not compatible */ +#define SND_ERROR_BEGIN 500000 /**< Lower boundary of sound error codes. */ +#define SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0) /**< Kernel/library protocols are not compatible. */ 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 + * \brief Error handler callback. + * \param file Source file name. + * \param line Line number. + * \param function Function name. + * \param err Value of \c errno, or 0 if not relevant. + * \param fmt \c printf(3) format. + * \param ... \c printf(3) arguments. + * + * A function of this type is called by the ALSA library when an error occurs. + * This function usually shows the message on the screen, and/or logs it. */ -typedef void (snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((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); +typedef void (*snd_lib_error_handler_t)(const char *file, int line, const char *function, int err, const char *fmt, ...) /* __attribute__ ((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); #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 95) -#define SNDERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, __VA_ARGS__) /**< show sound error */ -#define SYSERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, __VA_ARGS__) /**< show system error */ +#define SNDERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, __VA_ARGS__) /**< Shows a sound error message. */ +#define SYSERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, __VA_ARGS__) /**< Shows a system error message (related to \c errno). */ #else -#define SNDERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, ##args) /**< show sound error */ -#define SYSERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, ##args) /**< show system error */ +#define SNDERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, ##args) /**< Shows a sound error message. */ +#define SYSERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, ##args) /**< Shows a system error message (related to \c errno). */ #endif /** \} */ diff --git a/include/global.h b/include/global.h index f169ad01..8334e9f5 100644 --- a/include/global.h +++ b/include/global.h @@ -35,6 +35,9 @@ extern "C" { /** * \defgroup Global Global defines and functions * Global defines and functions. + * \par + * The ALSA library implementation uses these macros and functions. + * Most applications probably do not need them. * \{ */ @@ -45,9 +48,12 @@ extern "C" { #ifdef PIC /* dynamic build */ -/** helper macro for SND_DLSYM_BUILD_VERSION \hideinitializer */ +/** \hideinitializer \brief Helper macro for #SND_DLSYM_BUILD_VERSION. */ #define __SND_DLSYM_VERSION(name, version) _ ## name ## version -/** build version for versioned dynamic symbol \hideinitializer */ +/** + * \hideinitializer + * \brief Appends the build version to the name of a versioned dynamic symbol. + */ #define SND_DLSYM_BUILD_VERSION(name, version) char __SND_DLSYM_VERSION(name, version); #else /* static build */ @@ -60,9 +66,12 @@ struct snd_dlsym_link { extern struct snd_dlsym_link *snd_dlsym_start; -/** helper macro for SND_DLSYM_BUILD_VERSION \hideinitializer */ +/** \hideinitializer \brief Helper macro for #SND_DLSYM_BUILD_VERSION. */ #define __SND_DLSYM_VERSION(prefix, name, version) _ ## prefix ## name ## version -/** build version for versioned dynamic symbol \hideinitializer */ +/** + * \hideinitializer + * \brief Appends the build version to the name of a versioned dynamic symbol. + */ #define SND_DLSYM_BUILD_VERSION(name, version) \ static struct snd_dlsym_link __SND_DLSYM_VERSION(snd_dlsym_, name, version); \ void __SND_DLSYM_VERSION(snd_dlsym_constructor_, name, version) (void) __attribute__ ((constructor)); \ @@ -75,7 +84,7 @@ extern struct snd_dlsym_link *snd_dlsym_start; #endif -/** get version of dynamic symbol as string */ +/** \brief Returns the version of a dynamic symbol as a string. */ #define SND_DLSYM_VERSION(version) __STRING(version) void *snd_dlopen(const char *file, int mode); @@ -83,10 +92,19 @@ void *snd_dlsym(void *handle, const char *name, const char *version); int snd_dlclose(void *handle); -/** Async notification client handler */ +/** + * \brief Internal structure for an async notification client handler. + * + * The ALSA library uses a pointer to this structure as a handle to an async + * notification object. Applications don't access its contents directly. + */ typedef struct _snd_async_handler snd_async_handler_t; -/** Async notification callback */ +/** + * \brief Async notification callback. + * + * See the #snd_async_add_handler function for details. + */ typedef void (*snd_async_callback_t)(snd_async_handler_t *handler); int snd_async_add_handler(snd_async_handler_t **handler, int fd, diff --git a/include/input.h b/include/input.h index 8d0c5cf8..105b1288 100644 --- a/include/input.h +++ b/include/input.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Application interface library for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -34,18 +34,30 @@ extern "C" { /** * \defgroup Input Input Interface - * Input Interface + * + * The input functions present an interface similar to the stdio functions + * on top of different underlying input sources. + * + * The #snd_config_load function uses such an input handle to be able to + * load configurations not only from standard files but also from other + * sources, e.g. from memory buffers. + * * \{ */ -/** Input handle */ +/** + * \brief Internal structure for an input object. + * + * The ALSA library uses a pointer to this structure as a handle to an + * input object. Applications don't access its contents directly. + */ typedef struct _snd_input snd_input_t; -/** Input type */ +/** Input type. */ typedef enum _snd_input_type { - /** Input from a stdio stream */ + /** Input from a stdio stream. */ SND_INPUT_STDIO, - /** Input from a memory buffer */ + /** Input from a memory buffer. */ SND_INPUT_BUFFER } snd_input_type_t; @@ -53,7 +65,11 @@ int snd_input_stdio_open(snd_input_t **inputp, const char *file, const char *mod int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close); int snd_input_buffer_open(snd_input_t **inputp, const char *buffer, ssize_t size); int snd_input_close(snd_input_t *input); -int snd_input_scanf(snd_input_t *input, const char *format, ...) __attribute__ ((format (scanf, 2, 3))); +int snd_input_scanf(snd_input_t *input, const char *format, ...) +#ifndef DOC_HIDDEN + __attribute__ ((format (scanf, 2, 3))) +#endif + ; char *snd_input_gets(snd_input_t *input, char *str, size_t size); int snd_input_getc(snd_input_t *input); int snd_input_ungetc(snd_input_t *input, int c); diff --git a/include/output.h b/include/output.h index 4ca05345..492d712c 100644 --- a/include/output.h +++ b/include/output.h @@ -7,8 +7,8 @@ * \date 1998-2001 * * Application interface library for the ALSA driver - * - * + */ +/* * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of @@ -34,18 +34,30 @@ extern "C" { /** * \defgroup Output Output Interface - * Output Interface + * + * The output functions present an interface similar to the stdio functions + * on top of different underlying output destinations. + * + * Many PCM debugging functions (\c snd_pcm_xxx_dump_xxx) use such an output + * handle to be able to write not only to the screen but also to other + * destinations, e.g. to files or to memory buffers. + * * \{ */ -/** Output handle */ +/** + * \brief Internal structure for an output object. + * + * The ALSA library uses a pointer to this structure as a handle to an + * output object. Applications don't access its contents directly. + */ typedef struct _snd_output snd_output_t; -/** Output type */ +/** Output type. */ typedef enum _snd_output_type { - /** Output to a stdio stream */ + /** Output to a stdio stream. */ SND_OUTPUT_STDIO, - /** Output to a memory buffer */ + /** Output to a memory buffer. */ SND_OUTPUT_BUFFER } snd_output_type_t; @@ -54,7 +66,11 @@ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close); int snd_output_buffer_open(snd_output_t **outputp); size_t snd_output_buffer_string(snd_output_t *output, char **buf); int snd_output_close(snd_output_t *output); -int snd_output_printf(snd_output_t *output, const char *format, ...) __attribute__ ((format (printf, 2, 3))); +int snd_output_printf(snd_output_t *output, const char *format, ...) +#ifndef DOC_HIDDEN + __attribute__ ((format (printf, 2, 3))) +#endif + ; int snd_output_puts(snd_output_t *output, const char *str); int snd_output_putc(snd_output_t *output, int c); int snd_output_flush(snd_output_t *output); diff --git a/src/async.c b/src/async.c index e1d7ffb3..16fd24f3 100644 --- a/src/async.c +++ b/src/async.c @@ -63,17 +63,33 @@ static void snd_async_handler(int signo ATTRIBUTE_UNUSED, siginfo_t *siginfo, vo } /** - * \brief Add async handler - * \param handler Result - async handler - * \param fd - File descriptor - * \param callback - Async callback - * \param private_data - Private data for async callback - * \result zero if success, otherwise a negative error code + * \brief Registers an async handler. + * \param handler The function puts the pointer to the new async handler + * object at the address specified by \p handler. + * \param fd The file descriptor to be associated with the callback. + * \param callback The async callback function. + * \param private_data Private data for the async callback function. + * \result Zero if successful, otherwise a negative error code. * - * The function create the async handler. The ALSA extension - * for the standard SIGIO signal contains the multiplexer - * for multiple asynchronous notifiers using one sigaction - * callback. + * This function associates the callback function with the given file, + * and saves this association in a \c snd_async_handler_t object. + * + * Whenever the \c SIGIO signal is raised for the file \p fd, the callback + * function will be called with its parameter pointing to the async handler + * object returned by this function. + * + * The ALSA \c sigaction handler for the \c SIGIO signal automatically + * multiplexes the notifications to the registered async callbacks. + * However, the application is responsible for instructing the device driver + * to generate the \c SIGIO signal. + * + * The \c SIGIO signal may have been replaced with another signal, + * see #snd_async_handler_get_signo. + * + * When the async handler isn't needed anymore, you must delete it with + * #snd_async_del_handler. + * + * \see snd_async_add_pcm_handler, snd_async_add_ctl_handler */ int snd_async_add_handler(snd_async_handler_t **handler, int fd, snd_async_callback_t callback, void *private_data) @@ -108,9 +124,9 @@ int snd_async_add_handler(snd_async_handler_t **handler, int fd, } /** - * \brief Delete async handler - * \param handler Async handler to delete - * \result zero if success, otherwise a negative error code + * \brief Deletes an async handler. + * \param handler Handle of the async handler to delete. + * \result Zero if successful, otherwise a negative error code. */ int snd_async_del_handler(snd_async_handler_t *handler) { @@ -150,9 +166,13 @@ int snd_async_del_handler(snd_async_handler_t *handler) } /** - * \brief Get signal number assigned to async handler - * \param handler Async handler - * \result signal number if success, otherwise a negative error code + * \brief Returns the signal number assigned to an async handler. + * \param handler Handle to an async handler. + * \result The signal number if successful, otherwise a negative error code. + * + * The signal number for async handlers usually is \c SIGIO, + * but wizards can redefine it to a realtime signal + * when compiling the ALSA library. */ int snd_async_handler_get_signo(snd_async_handler_t *handler) { @@ -161,9 +181,9 @@ int snd_async_handler_get_signo(snd_async_handler_t *handler) } /** - * \brief Get file descriptor assigned to async handler - * \param handler Async handler - * \result file descriptor if success, otherwise a negative error code + * \brief Returns the file descriptor assigned to an async handler. + * \param handler Handle to an async handler. + * \result The file descriptor if successful, otherwise a negative error code. */ int snd_async_handler_get_fd(snd_async_handler_t *handler) { @@ -172,9 +192,9 @@ int snd_async_handler_get_fd(snd_async_handler_t *handler) } /** - * \brief Get private data assigned to async handler - * \param handler Async handler - * \result private data if success, otherwise a negative error code + * \brief Returns the private data assigned to an async handler. + * \param handler Handle to an async handler. + * \result The \c private_data value registered with the async handler. */ void *snd_async_handler_get_callback_private(snd_async_handler_t *handler) { diff --git a/src/conf.c b/src/conf.c index a71219a0..0f4aac60 100644 --- a/src/conf.c +++ b/src/conf.c @@ -34,13 +34,13 @@ /*! \page conf Configuration files -

Configuration files are using a simple format allowing the modern +

Configuration files use a simple format allowing modern data description like nesting and array assignments.

\section conf_whitespace Whitespace Whitespace is the collective name given to spaces (blanks), horizontal and -vertical tabs, newline characters, and comments. Whitespace can serve to +vertical tabs, newline characters, and comments. Whitespace can indicate where configuration tokens start and end, but beyond this function, any surplus whitespace is discarded. For example, the two sequences @@ -65,7 +65,7 @@ b \endcode The ASCII characters representing whitespace can occur within literal -strings, int which case they are protected from the normal parsing process +strings, in which case they are protected from the normal parsing process (they remain as part of the string). For example: \code @@ -75,12 +75,11 @@ strings, int which case they are protected from the normal parsing process parses to two tokens, including the single literal-string token "John Smith". -\section conf_linesplicing Line splicing with \ +\section conf_linesplicing Line continuation with \ -A special case occurs, if the final newline character encountered is -preceded by a backslash (\) in the string value definition. The backslash -and new line are both discarded, allowing two physical lines of text to be -treated as one unit. +A special case occurs if a newline character in a string is preceded +by a backslash (\). The backslash and the new line are both discarded, +allowing two physical lines of text to be treated as one unit. \code "John \ @@ -91,17 +90,17 @@ is parsed as "John Smith". \section conf_comments Comments -A single-line comments are defined using character #. The comment can start -in any position, and extends until the next new line. +A single-line comment begins with the character #. The comment can start +at any position, and extends to the end of the line. \code a 1 # this is a comment \endcode -\section conf_include Include another configuration file +\section conf_include Including configuration files -A new configuration file can be included using syntax. The global -configuration directory can be referenced using syntax. +To include another configuration file, write the file name in angle brackets. +The prefix \c confdir: will reference the global configuration directory. \code @@ -118,7 +117,7 @@ The configuration punctuators (also known as separators) are: \subsection conf_braces Braces -Open and close braces { } indicate the start and end of a compound +Opening and closing braces { } indicate the start and end of a compound statement: \code @@ -129,8 +128,8 @@ a { \subsection conf_brackets Brackets -Open and close brackets indicate single array definition. The identifiers -are automatically generated starting with zero. +Opening and closing brackets indicate a single array definition. The +identifiers are automatically generated starting with zero. \code a [ @@ -139,7 +138,7 @@ a [ ] \endcode -Above code is equal to +The above code is equal to \code a.0 "first" @@ -148,9 +147,9 @@ a.1 "second" \subsection conf_comma_semicolon Comma and semicolon -The comma (,) or semicolon (;) can separate the value assignments. It is not -strictly required to use these separators, because any whitespace supplies -them. +The comma (,) or semicolon (;) can separate value assignments. It is not +strictly required to use these separators because whitespace suffices to +separate tokens. \code a 1; @@ -159,7 +158,7 @@ b 1, \subsection conf_equal Equal sign -The equal sign (=) separates can separate variable declarations from +The equal sign (=) can separate variable declarations from initialization lists: \code @@ -167,16 +166,17 @@ a=1 b=2 \endcode -Using the equal signs is not required, because any whitespace supplies -them. +Using equal signs is not required because whitespace suffices to separate +tokens. -\section conf_assigns Assigns +\section conf_assigns Assignments The configuration file defines id (key) and value pairs. The id (key) can be -composed from any ASCII digits or chars from a to z or A to Z, including -char _. The value can be either a string, integer or real number. +composed from ASCII digits, characters from a to z and A to Z, and the +underscore (_). The value can be either a string, an integer, a real number, +or a compound statement. -\subsection conf_single Single assign +\subsection conf_single Single assignments \code a 1 # is equal to @@ -185,7 +185,7 @@ a=1; # is equal to a 1, \endcode -\subsection conf_compound Compound assign (definition using braces) +\subsection conf_compound Compound assignments (definitions using braces) \code a { @@ -196,14 +196,14 @@ a={ } \endcode -\section conf_compound1 Compound assign (one key definition) +\section conf_compound1 Compound assignments (one key definitions) \code a.b 1 a.b=1 \endcode -\subsection conf_array Array assign (definition using brackets) +\subsection conf_array Array assignments (definitions using brackets) \code a [ @@ -212,31 +212,31 @@ a [ ] \endcode -\subsection conf_array1 Array assign (one key definition) +\subsection conf_array1 Array assignments (one key definitions) \code a.0 "first" a.1 "second" \endcode -\section conf_mode Parsed node operation mode +\section conf_mode Operation modes for parsing nodes -By default, the node operation node is 'merge+create'. It means, if +By default, the node operation mode is 'merge+create', i.e., if a configuration node is not present a new one is created, otherwise the latest assignment is merged (if possible - type checking). The -'merge+create' operation mode is specified with a prefix char plus (+). +'merge+create' operation mode is specified with the prefix character plus (+). -The operation mode 'merge' merges the node with old one (which must -exists). Type checking is done, so string cannot be assigned to integer -and so on. This mode is specified with a prefix char minus (-). +The operation mode 'merge' merges the node with the old one (which must +exist). Type checking is done, so strings cannot be assigned to integers +and so on. This mode is specified with the prefix character minus (-). The operation mode 'do not override' ignores a new configuration node -if a configuration node with same name exists. This mode is specified with -a prefix char note of interrogation (?). +if a configuration node with the same name exists. This mode is specified with +the prefix character question mark (?). The operation mode 'override' always overrides the old configuration node -with new contents. This mode is specified with a prefix char note of -exclamation (!). +with new contents. This mode is specified with the prefix character +exclamation mark (!). \code defaults.pcm.!device 1 @@ -250,26 +250,26 @@ defaults.pcm.!device 1 # Include a new configuration file -# Simple assign +# Simple assignment name [=] value [,|;] -# Compound assign (first style) +# Compound assignment (first style) name [=] { name1 [=] value [,|;] ... } -# Compound assign (second style) +# Compound assignment (second style) name.name1 [=] value [,|;] -# Array assign (first style) +# Array assignment (first style) name [ value0 [,|;] value1 [,|;] ... ] -# Array assign (second style) +# Array assignment (second style) name.0 [=] value0 [,|;] name.1 [=] value1 [,|;] \endcode @@ -282,26 +282,26 @@ name.1 [=] value1 [,|;] */ -/*! \page confarg Configuration - runtime arguments +/*! \page confarg Runtime arguments in configuration files

The ALSA library can accept runtime arguments for some configuration -blocks. This extension is on top of the basic syntax of the configuration -files.

+blocks. This extension is built on top of the basic configuration file +syntax.

\section confarg_define Defining arguments -Arguments are specified by id (key) @args and array values containing -the string names of arguments: +Arguments are defined using the id (key) \c @args and array values containing +the string names of the arguments: \code @args [ CARD ] # or @args.0 CARD \endcode -\section confarg_type Defining argument type and default value +\section confarg_type Defining argument types and default values -Arguments type is specified by id (key) @args and argument name. The type -and default value is specified in the compound: +An argument's type is specified with the id (key) \c @args and the argument +name. The type and the default value are specified in the compound block: \code @args.CARD { @@ -310,9 +310,9 @@ and default value is specified in the compound: } \endcode -\section confarg_refer Referring argument +\section confarg_refer Referring to arguments -Arguments are referred by dollar-sign ($) and name of argument: +Arguments are referred to with a dollar-sign ($) and the name of the argument: \code card $CARD @@ -320,8 +320,9 @@ Arguments are referred by dollar-sign ($) and name of argument: \section confarg_usage Usage -Arguments are replaced with real values when the key contains part after -colon (:). For example, all these names for PCM interface gives same result: +To use a block with arguments, write the argument values after the key, +separated with a colon (:). For example, all these names for PCM interfaces +give the same result: \code hw:0,1 @@ -331,9 +332,9 @@ plug:"hw:0,1" plug:{SLAVE="hw:{CARD 0 DEV 1}"} \endcode -As you see, the argument can be specified by order or by name. Note that -arguments closed into braces are parsed in same way like configuration files, -but with the override method by default. +As you see, arguments can be specified in their proper order or by name. +Note that arguments enclosed in braces are parsed in the same way as in +configuration files, but using the override method by default. \section confarg_example Example @@ -356,17 +357,17 @@ pcm.demo { */ -/*! \page conffunc Configuration - runtime functions +/*! \page conffunc Runtime functions in configuration files -

The ALSA library accepts the runtime modification of configuration. -The several build-in functions are available.

+

The ALSA library can modify the configuration at runtime. +Several built-in functions are available.

-

The function is referred using id @func and function name. All other +

A function is defined with the id \c @func and the function name. All other values in the current compound are used as configuration for the function. -If compound func. is defined in the root leafs, then library -and function from this compound configuration is used, otherwise the prefix -'snd_func_' is added to string and the code from the ALSA library is used. -The definition of function looks like:

+If the compound func. is defined in the root node, then the +library and function from this compound configuration are used, otherwise +'snd_func_' is prefixed to the string and code from the ALSA library is used. +The definition of a function looks like:

\code func.remove_first_char { @@ -377,13 +378,14 @@ func.remove_first_char { */ -/*! \page confhooks Configuration - hooks +/*! \page confhooks Hooks in configuration files -

The hook extension in the ALSA library allows expanding of configuration -nodes at run-time lookup. The presence of a hook is determined with a @hooks -compound node.

+

The hook extension in the ALSA library allows expansion of configuration +nodes at run-time. The existence of a hook is determined by the +presence of a @hooks compound node.

-

The example definition a hook which loads two configuration files at beginning:

+

This example defines a hook which loads two configuration files at the +beginning:

\code @hooks [ @@ -401,12 +403,12 @@ compound node.

\section confhooks_ref Function reference
    -
  • The function load - snd_config_hook_load() - loads and parses the given - configuration files. -
  • The function load_for_all_cards - snd_config_hook_load_for_all_cards() - - loads and parses the given configuration files for all installed sound-cards. - The driver name (type of sound-card) is passed in the private configuration - node. +
  • The function load - \c snd_config_hook_load() - loads and parses the + given configuration files. +
  • The function load_for_all_cards - \c snd_config_hook_load_for_all_cards() - + loads and parses the given configuration files for each installed sound + card. The driver name (the type of the sound card) is passed in the + private configuration node.
*/ @@ -460,7 +462,7 @@ typedef struct { int ch; } input_t; -int safe_strtoll(const char *str, long long *val) +static int safe_strtoll(const char *str, long long *val) { long long v; int endidx; @@ -1389,17 +1391,19 @@ static int _snd_config_save_leaves(snd_config_t *config, snd_output_t *out, unsi /** - * \brief Substitute one node to another - * \param dst Destination node - * \param src Source node (invalid after call) - * \return zero if success, otherwise a negative error code + * \brief Substitutes one configuration node to another. + * \param dst Handle to the destination node. + * \param src Handle to the source node. Must not be the same as \p dst. + * \return Zero if successful, otherwise a negative error code. * * If both nodes are compounds, the source compound node members are * appended to the destination compound node. * * If the destination node is a compound and the source node is * an ordinary type, the compound members are deleted (including - * contents). + * their contents). + * + * A successful call to this function invalidates the source node. */ int snd_config_substitute(snd_config_t *dst, snd_config_t *src) { @@ -1429,9 +1433,11 @@ int snd_config_substitute(snd_config_t *dst, snd_config_t *src) } /** - * \brief Return type of a config node from an ASCII string - * \param config Config node handle - * \return node type + * \brief Converts an ASCII string to a configuration node type. + * \param ascii A string containing a configuration node type. + * \param type The function puts the node type at the address specified + * by \p type. + * \return Zero if successgul, otherwise a negative error code. */ int snd_config_get_type_ascii(const char *ascii, snd_config_type_t *type) { @@ -1460,9 +1466,9 @@ int snd_config_get_type_ascii(const char *ascii, snd_config_type_t *type) } /** - * \brief Return type of a config node - * \param config Config node handle - * \return node type + * \brief Returns the type of a configuration node. + * \param config Handle to the configuration node. + * \return The node's type. */ snd_config_type_t snd_config_get_type(const snd_config_t *config) { @@ -1470,10 +1476,14 @@ snd_config_type_t snd_config_get_type(const snd_config_t *config) } /** - * \brief Return id of a config node - * \param config Config node handle - * \param value The result id - * \return 0 on success otherwise a negative error code + * \brief Returns the id of a configuration node. + * \param config Handle to the configuration node. + * \param id The function puts the pointer to the id string at the address + * specified by \p id. + * \return Zero if successful, otherwise a negative error code. + * + * The returned string is owned by the configuration node; the application + * must not modify or delete it. */ int snd_config_get_id(const snd_config_t *config, const char **id) { @@ -1483,10 +1493,11 @@ int snd_config_get_id(const snd_config_t *config, const char **id) } /** - * \brief Set id of a config node - * \param config Config node handle - * \return id Node id - * \return 0 on success otherwise a negative error code + * \brief Sets the id of a configuration node. + * \param config Handle to the configuration node. + * \param id The new node id. + * \return Zero if successful, otherwise a negative error code. + * \bug \p id must not be a pointer to the node's current id. */ int snd_config_set_id(snd_config_t *config, const char *id) { @@ -1500,9 +1511,12 @@ int snd_config_set_id(snd_config_t *config, const char *id) } /** - * \brief Build a top level config node - * \param config Returned config node handle pointer - * \return 0 on success otherwise a negative error code + * \brief Creates a top level configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \return Zero if successful, otherwise a negative error code. + * + * The returned node is a compound node. */ int snd_config_top(snd_config_t **config) { @@ -1568,10 +1582,10 @@ static int snd_config_load1(snd_config_t *config, snd_input_t *in, int override) } /** - * \brief Load a config tree - * \param config Config top node handle - * \param in Input handle - * \return 0 on success otherwise a negative error code + * \brief Loads a configuration tree. + * \param config Handle to a top level configuration node. + * \param in Input handle to read the configuration from. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_load(snd_config_t *config, snd_input_t *in) { @@ -1579,10 +1593,10 @@ int snd_config_load(snd_config_t *config, snd_input_t *in) } /** - * \brief Load a config tree and override existing configuration nodes - * \param config Config top node handle - * \param in Input handle - * \return 0 on success otherwise a negative error code + * \brief Loads a configuration tree and overrides existing configuration nodes. + * \param config Handle to a top level configuration node. + * \param in Input handle to read the configuration from. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_load_override(snd_config_t *config, snd_input_t *in) { @@ -1590,10 +1604,10 @@ int snd_config_load_override(snd_config_t *config, snd_input_t *in) } /** - * \brief Add a leaf to a config compound node - * \param father Config compound node handle - * \param leaf Leaf config node handle - * \return 0 on success otherwise a negative error code + * \brief Adds a child to a compound configuration node. + * \param father Handle to the compound configuration node. + * \param leaf Handle to the configuration node to be added to \p father. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_add(snd_config_t *father, snd_config_t *leaf) { @@ -1610,9 +1624,11 @@ int snd_config_add(snd_config_t *father, snd_config_t *leaf) } /** - * \brief Remove a leaf config node from tree - * \param config Config node handle - * \return 0 on success otherwise a negative error code + * \brief Removes a configuration node from its tree. + * \param config Handle to the configuration node to be removed. + * \return Zero if successful, otherwise a negative error code. + * + * This functions does \e not delete the removed node. */ int snd_config_remove(snd_config_t *config) { @@ -1624,9 +1640,13 @@ int snd_config_remove(snd_config_t *config) } /** - * \brief Remove a leaf config node (freeing all the related resources) - * \param config Config node handle - * \return 0 on success otherwise a negative error code + * \brief Deletes a configuration node (freeing all its related resources). + * \param config Handle to the configuration node to be deleted. + * \return Zero if successful, otherwise a negative error code. + * + * If the node is a child node, it is removed from the tree before being + * deleted. If the node is a compound node, all children are deleted + * recursively. */ int snd_config_delete(snd_config_t *config) { @@ -1663,9 +1683,11 @@ int snd_config_delete(snd_config_t *config) } /** - * \brief Remove a compound config node members (freeing all the related resources) - * \param config Compound config node handle - * \return 0 on success otherwise a negative error code + * \brief Deletes the children of a compound configuration node (freeing all its related resources) + * \param config Handle to the compound configuration node. + * \return Zero if successful, otherwise a negative error code. + * + * Any compound nodes among the children of \p config are deleted recursively. */ int snd_config_delete_compound_members(const snd_config_t *config) { @@ -1688,11 +1710,12 @@ int snd_config_delete_compound_members(const snd_config_t *config) } /** - * \brief Build a config node - * \param config Returned config node handle pointer - * \param id Node id - * \param type Node type - * \return 0 on success otherwise a negative error code + * \brief Creates a configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param type The type of the new node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_make(snd_config_t **config, const char *id, snd_config_type_t type) @@ -1709,10 +1732,13 @@ int snd_config_make(snd_config_t **config, const char *id, } /** - * \brief Build an integer config node - * \param config Returned config node handle pointer - * \param id Node id - * \return 0 on success otherwise a negative error code + * \brief Creates an integer configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \return Zero if successful, otherwise a negative error code. + * + * The value of the new node is 0. */ int snd_config_make_integer(snd_config_t **config, const char *id) { @@ -1720,10 +1746,13 @@ int snd_config_make_integer(snd_config_t **config, const char *id) } /** - * \brief Build an integer64 config node - * \param config Returned config node handle pointer - * \param id Node id - * \return 0 on success otherwise a negative error code + * \brief Creates an integer64 configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \return Zero if successful, otherwise a negative error code. + * + * The value of the new node is 0. */ int snd_config_make_integer64(snd_config_t **config, const char *id) { @@ -1731,10 +1760,13 @@ int snd_config_make_integer64(snd_config_t **config, const char *id) } /** - * \brief Build a real config node - * \param config Returned config node handle pointer - * \param id Node id - * \return 0 on success otherwise a negative error code + * \brief Creates a real configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \return Zero if successful, otherwise a negative error code. + * + * The value of the new node is 0.0. */ int snd_config_make_real(snd_config_t **config, const char *id) { @@ -1742,10 +1774,13 @@ int snd_config_make_real(snd_config_t **config, const char *id) } /** - * \brief Build a string config node - * \param config Returned config node handle pointer - * \param id Node id - * \return 0 on success otherwise a negative error code + * \brief Creates a string configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \return Zero if successful, otherwise a negative error code. + * + * The value of the new node is \c NULL. */ int snd_config_make_string(snd_config_t **config, const char *id) { @@ -1753,10 +1788,13 @@ int snd_config_make_string(snd_config_t **config, const char *id) } /** - * \brief Build a pointer config node - * \param config Returned config node handle pointer - * \param id Node id - * \return 0 on success otherwise a negative error code + * \brief Creates a pointer configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \return Zero if successful, otherwise a negative error code. + * + * The value of the new node is \c NULL. */ int snd_config_make_pointer(snd_config_t **config, const char *id) { @@ -1764,11 +1802,13 @@ int snd_config_make_pointer(snd_config_t **config, const char *id) } /** - * \brief Build an empty compound config node - * \param config Returned config node handle pointer - * \param id Node id - * \param join Join flag (checked in snd_config_save to change look) - * \return 0 on success otherwise a negative error code + * \brief Creates an empty compound configuration node. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param join Join flag. + * This is checked in #snd_config_save to change look. (Huh?) + * \return Zero if successful, otherwise a negative error code. */ int snd_config_make_compound(snd_config_t **config, const char *id, int join) @@ -1782,11 +1822,12 @@ int snd_config_make_compound(snd_config_t **config, const char *id, } /** - * \brief Build an integer config node and use given initial value - * \param config Returned config node handle pointer - * \param id Node id - * \param value Initial value - * \return 0 on success otherwise a negative error code + * \brief Creates an integer configuration node with the given initial value. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param value The initial value of the new node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_imake_integer(snd_config_t **config, const char *id, const long value) { @@ -1800,11 +1841,12 @@ int snd_config_imake_integer(snd_config_t **config, const char *id, const long v } /** - * \brief Build an integer64 config node and use given initial value - * \param config Returned config node handle pointer - * \param id Node id - * \param value Initial value - * \return 0 on success otherwise a negative error code + * \brief Creates an integer configuration node with the given initial value. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param value The initial value of the new node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_imake_integer64(snd_config_t **config, const char *id, const long long value) { @@ -1818,11 +1860,12 @@ int snd_config_imake_integer64(snd_config_t **config, const char *id, const long } /** - * \brief Build a real config node and use given initial value - * \param config Returned config node handle pointer - * \param id Node id - * \param value Initial value - * \return 0 on success otherwise a negative error code + * \brief Creates a real configuration node with the given initial value. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param value The initial value of the new node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_imake_real(snd_config_t **config, const char *id, const double value) { @@ -1836,11 +1879,14 @@ int snd_config_imake_real(snd_config_t **config, const char *id, const double va } /** - * \brief Build a string config node and use given initial value - * \param config Returned config node handle pointer - * \param id Node id - * \param value Initial value - * \return 0 on success otherwise a negative error code + * \brief Creates a string configuration node with the given initial value. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param value The initial value of the new node. May be \c NULL. + * \return Zero if successful, otherwise a negative error code. + * + * This function creates the new node with its own copy of the passed string. */ int snd_config_imake_string(snd_config_t **config, const char *id, const char *value) { @@ -1864,11 +1910,12 @@ int snd_config_imake_string(snd_config_t **config, const char *id, const char *v } /** - * \brief Build a pointer config node and use given initial value - * \param config Returned config node handle pointer - * \param id Node id - * \param value Initial value - * \return 0 on success otherwise a negative error code + * \brief Creates a pointer configuration node with the given initial value. + * \param config The function puts the handle to the new node at the address + * specified by \p config. + * \param id The id of the new node. + * \param value The initial value of the new node. May be \c NULL. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_imake_pointer(snd_config_t **config, const char *id, const void *value) { @@ -1882,10 +1929,10 @@ int snd_config_imake_pointer(snd_config_t **config, const char *id, const void * } /** - * \brief Change the value of an integer config node - * \param config Config node handle - * \param value Value - * \return 0 on success otherwise a negative error code + * \brief Changes the value of an integer configuration node. + * \param config Handle to the configuration node. + * \param value The new value for the node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_set_integer(snd_config_t *config, long value) { @@ -1897,10 +1944,10 @@ int snd_config_set_integer(snd_config_t *config, long value) } /** - * \brief Change the value of an integer64 config node - * \param config Config node handle - * \param value Value - * \return 0 on success otherwise a negative error code + * \brief Changes the value of an integer64 configuration node. + * \param config Handle to the configuration node. + * \param value The new value for the node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_set_integer64(snd_config_t *config, long long value) { @@ -1912,10 +1959,10 @@ int snd_config_set_integer64(snd_config_t *config, long long value) } /** - * \brief Change the value of a real config node - * \param config Config node handle - * \param value Value - * \return 0 on success otherwise a negative error code + * \brief Changes the value of a real configuration node. + * \param config Handle to the configuration node. + * \param value The new value for the node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_set_real(snd_config_t *config, double value) { @@ -1927,10 +1974,15 @@ int snd_config_set_real(snd_config_t *config, double value) } /** - * \brief Change the value of a string config node - * \param config Config node handle - * \param value Value - * \return 0 on success otherwise a negative error code + * \brief Changes the value of a string configuration node. + * \param config Handle to the configuration node. + * \param value The new value for the node. May be \c NULL. + * \return Zero if successful, otherwise a negative error code. + * + * This function deletes the old string in the node and stores a copy of + * the passed string in the node. + * + * \bug \p value must not be a pointer to the node's current value. */ int snd_config_set_string(snd_config_t *config, const char *value) { @@ -1950,10 +2002,12 @@ int snd_config_set_string(snd_config_t *config, const char *value) } /** - * \brief Change the value of a pointer config node - * \param config Config node handle - * \param ptr Value - * \return 0 on success otherwise a negative error code + * \brief Changes the value of a pointer configuration node. + * \param config Handle to the configuration node. + * \param value The new value for the node. May be \c NULL. + * \return Zero if successful, otherwise a negative error code. + * + * This function does not free the old pointer in the node. */ int snd_config_set_pointer(snd_config_t *config, const void *value) { @@ -1965,10 +2019,15 @@ int snd_config_set_pointer(snd_config_t *config, const void *value) } /** - * \brief Change the value of a config node - * \param config Config node handle - * \param ascii Value in ASCII form - * \return 0 on success otherwise a negative error code + * \brief Changes the value of a configuration node. + * \param config Handle to the configuration node. + * \param ascii The new value for the node as an ASCII string. \p ascii must + * not be \c NULL, not even for a string node. + * \return Zero if successful, otherwise a negative error code. + * + * The node must have a simple type, and the new value must have the same type. + * + * \bug For string nodes, changing the length of the string doesn't work. */ int snd_config_set_ascii(snd_config_t *config, const char *ascii) { @@ -2016,10 +2075,11 @@ int snd_config_set_ascii(snd_config_t *config, const char *ascii) } /** - * \brief Get the value of an integer config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of an integer configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_get_integer(const snd_config_t *config, long *ptr) { @@ -2031,10 +2091,11 @@ int snd_config_get_integer(const snd_config_t *config, long *ptr) } /** - * \brief Get the value of an integer64 config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of an integer64 configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_get_integer64(const snd_config_t *config, long long *ptr) { @@ -2046,10 +2107,11 @@ int snd_config_get_integer64(const snd_config_t *config, long long *ptr) } /** - * \brief Get the value of a real config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of a real configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_get_real(const snd_config_t *config, double *ptr) { @@ -2061,13 +2123,14 @@ int snd_config_get_real(const snd_config_t *config, double *ptr) } /** - * \brief Get the value of a real or integer config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of a real or integer configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. * - * Note: If the config type is integer/integer64, it is converted - * to the double type on the fly. + * If the node's type is integer or integer64, the value is converted + * to the \c double type on the fly. */ int snd_config_get_ireal(const snd_config_t *config, double *ptr) { @@ -2084,10 +2147,14 @@ int snd_config_get_ireal(const snd_config_t *config, double *ptr) } /** - * \brief Get the value of a string config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of a string configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. + * + * The returned string is owned by the configuration node; the application + * must not modify or delete it. */ int snd_config_get_string(const snd_config_t *config, const char **ptr) { @@ -2099,10 +2166,11 @@ int snd_config_get_string(const snd_config_t *config, const char **ptr) } /** - * \brief Get the value of a pointer config node - * \param config Config node handle - * \param ptr Returned value pointer - * \return 0 on success otherwise a negative error code + * \brief Returns the value of a pointer configuration node. + * \param config Handle to the configuration node. + * \param ptr The function puts the node's value at the address specified + * by \p ptr. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_get_pointer(const snd_config_t *config, const void **ptr) { @@ -2114,10 +2182,14 @@ int snd_config_get_pointer(const snd_config_t *config, const void **ptr) } /** - * \brief Get the value in ASCII form - * \param config Config node handle - * \param ascii Returned dynamically allocated ASCII string - * \return 0 on success otherwise a negative error code + * \brief Returns the value of a configuration node as a string. + * \param config Handle to the configuration node. + * \param ascii The function puts the pointer to the returned string at the + * address specified by \p ascii. + * \return Zero if successful, otherwise a negative error code. + * + * This function dynamically allocates the returned string. The application + * is responsible for deleting it with \c free() when it is no longer used. */ int snd_config_get_ascii(const snd_config_t *config, char **ascii) { @@ -2185,10 +2257,10 @@ int snd_config_get_ascii(const snd_config_t *config, char **ascii) } /** - * \brief Compare the config node id and given ASCII id - * \param config Config node handle - * \param id ASCII id - * \return the same value as result of the strcmp function + * \brief Compares the id of a configuration node to a given string. + * \param config Handle to the configuration node. + * \param id ASCII id. + * \return The same value as the result of the \c strcmp function. */ int snd_config_test_id(const snd_config_t *config, const char *id) { @@ -2197,10 +2269,10 @@ int snd_config_test_id(const snd_config_t *config, const char *id) } /** - * \brief Dump a config tree contents - * \param config Config node handle - * \param out Output handle - * \return 0 on success otherwise a negative error code + * \brief Dumps the contents of a configuration node or tree. + * \param config Handle to the (root) configuration node. + * \param out Output handle. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_save(snd_config_t *config, snd_output_t *out) { @@ -2336,11 +2408,12 @@ int snd_config_save(snd_config_t *config, snd_output_t *out) #endif /* DOC_HIDDEN */ /** - * \brief Search a node inside a config tree - * \param config Config node handle - * \param key Dot separated search key - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param key Search key: one or more node keys, separated with dots. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_search(snd_config_t *config, const char *key, snd_config_t **result) { @@ -2348,11 +2421,14 @@ int snd_config_search(snd_config_t *config, const char *key, snd_config_t **resu } /** - * \brief Search a node inside a config tree and expand aliases, excluding the top one - * \param config Config node handle - * \param key Dot separated search key - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, expanding aliases. + * \param root Handle to the root configuration node containing alias + * definitions. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param key Search key: one or more node keys, separated with dots. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_searcha(snd_config_t *root, snd_config_t *config, const char *key, snd_config_t **result) { @@ -2360,11 +2436,12 @@ int snd_config_searcha(snd_config_t *root, snd_config_t *config, const char *key } /** - * \brief Search a node inside a config tree - * \param config Config node handle - * \param result Pointer to found node - * \param ... one or more concatenated dot separated search key - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \param ... One or more concatenated dot separated search keys, terminated with \c NULL. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_searchv(snd_config_t *config, snd_config_t **result, ...) { @@ -2372,11 +2449,14 @@ int snd_config_searchv(snd_config_t *config, snd_config_t **result, ...) } /** - * \brief Search a node inside a config tree and expand aliases, excluding the top one - * \param config Config node handle - * \param result Pointer to found node - * \param ... one or more concatenated dot separated search key - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, expanding aliases. + * \param root Handle to the root configuration node containing alias + * definitions. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \param ... One or more concatenated dot separated search keys, terminated with \c NULL. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_searchva(snd_config_t *root, snd_config_t *config, snd_config_t **result, ...) { @@ -2384,15 +2464,16 @@ int snd_config_searchva(snd_config_t *root, snd_config_t *config, snd_config_t * } /** - * \brief Search a node inside a config tree using alias - * \param config Config node handle - * \param base Key base (or NULL) - * \param key Key suffix - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, using an alias. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param base Search key base, or \c NULL. + * \param key Search key suffix. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. * - * First key is tried and if nothing is found is tried base.key. - * If the value found is a string this is recursively tried in the + * First \c key is tried, then, if nothing is found, \c base.key is tried. + * If the value found is a string, this is recursively tried in the * same way. */ int snd_config_search_alias(snd_config_t *config, @@ -2404,11 +2485,12 @@ int snd_config_search_alias(snd_config_t *config, } /** - * \brief Search a node inside a config tree and expand hooks - * \param config Config node handle - * \param key Dot separated search key - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree and expands hooks. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param key Search key: one or more node keys, separated with dots. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_search_hooks(snd_config_t *config, const char *key, snd_config_t **result) { @@ -2421,11 +2503,14 @@ int snd_config_search_hooks(snd_config_t *config, const char *key, snd_config_t } /** - * \brief Search a node inside a config tree and expand aliases and hooks - * \param config Config node handle - * \param key Dot separated search key - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, expanding aliases and hooks. + * \param root Handle to the root configuration node containing alias + * definitions. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param key Search key: one or more node keys, separated with dots. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_searcha_hooks(snd_config_t *root, snd_config_t *config, const char *key, snd_config_t **result) { @@ -2439,11 +2524,14 @@ int snd_config_searcha_hooks(snd_config_t *root, snd_config_t *config, const cha } /** - * \brief Search a node inside a config tree and expand hooks and aliases - * \param config Config node handle - * \param result Pointer to found node - * \param ... one or more concatenated dot separated search key - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, expanding aliases and hooks. + * \param root Handle to the root configuration node containing alias + * definitions. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \param ... One or more concatenated dot separated search keys, terminated with \c NULL. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_searchva_hooks(snd_config_t *root, snd_config_t *config, snd_config_t **result, ...) @@ -2452,15 +2540,16 @@ int snd_config_searchva_hooks(snd_config_t *root, snd_config_t *config, } /** - * \brief Search a node inside a config tree using alias and expand hooks - * \param config Config node handle - * \param base Key base (or NULL) - * \param key Key suffix - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a node in a configuration tree, using an alias and expanding hooks. + * \param config Handle to the root of the configuration (sub)tree to search. + * \param base Search key base, or \c NULL. + * \param key Search key suffix. + * \param result The function puts the handle to the node found at the address + * specified by \p result. + * \return Zero if successful, otherwise a negative error code. * - * First key is tried and if nothing is found is tried base.key. - * If the value found is a string this is recursively tried in the + * First \c key is tried, then, if nothing is found, \c base.key is tried. + * If the value found is a string, this is recursively tried in the * same way. */ int snd_config_search_alias_hooks(snd_config_t *config, @@ -2472,14 +2561,16 @@ int snd_config_search_alias_hooks(snd_config_t *config, snd_config_searchva_hooks); } -/** Environment variable containing files list for #snd_config_update */ +/** The name of the environment variable containing the files list for #snd_config_update. */ #define ALSA_CONFIG_PATH_VAR "ALSA_CONFIG_PATH" -/** Default files used by #snd_config_update */ +/** The name of the default files used by #snd_config_update. */ #define ALSA_CONFIG_PATH_DEFAULT DATADIR "/alsa/alsa.conf" -/** \ingroup Config - * Config top node (global configuration) */ +/** + * \ingroup Config + * Configuration top level node (the global configuration). + */ snd_config_t *snd_config = NULL; struct finfo { @@ -2621,12 +2712,13 @@ static int snd_config_hooks(snd_config_t *config, snd_config_t *private_data) } /** - * \brief Load configuration from specified files - * \param root Configuration root node - * \param config Configuration node - * \param dst Destination node - * \param private_data Private data - * \return zero if success, otherwise a negative error code + * \brief Loads and parses the given configurations files. + * \param root Handle to the root configuration node. + * \param config Handle to the configuration node for this hook. + * \param dst The function puts the handle to the configuration node loaded + * from the file(s) at the address specified by \p dst. + * \param private_data Handle to the private data configuration node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_hook_load(snd_config_t *root, snd_config_t *config, snd_config_t **dst, snd_config_t *private_data) { @@ -2752,12 +2844,13 @@ int snd_determine_driver(int card, char **driver); #endif /** - * \brief Load configuration for all present cards - * \param root Configuration root node - * \param config Configuration node - * \param dst Destination node - * \param private_data Private data - * \return zero if success, otherwise a negative error code + * \brief Loads and parses the given configurations files for each installed sound card. + * \param root Handle to the root configuration node. + * \param config Handle to the configuration node for this hook. + * \param dst The function puts the handle to the configuration node loaded + * from the file(s) at the address specified by \p dst. + * \param private_data Handle to the private data configuration node. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_hook_load_for_all_cards(snd_config_t *root, snd_config_t *config, snd_config_t **dst, snd_config_t *private_data ATTRIBUTE_UNUSED) { @@ -2809,19 +2902,21 @@ SND_DLSYM_BUILD_VERSION(snd_config_hook_load_for_all_cards, SND_CONFIG_DLSYM_VER #endif /** - * \brief Update #snd_config rereading (if needed) configuration files. - * \param top Top node - * \param update Private update information - * \param cfgs Configuration files in list delimited with ':', if NULL -> default global - * configuration file is used - "/usr/share/alsa/alsa.conf". - * \return non-negative value on success, otherwise a negative error code - * \retval 0 no action is needed - * \retval 1 tree has been rebuild + * \brief Updates a configuration tree by rereading the configuration files (if needed). + * \param top Address of the handle to the top level node. + * \param update Address of a pointer to private update information. + * \param cfgs A list of configuration file names, delimited with ':'. + * If \p cfgs is set to \c NULL, the default global configuration + * file is used ("/usr/share/alsa/alsa.conf"). + * \return A non-negative value if successful, otherwise a negative error code. + * \retval 0 No action is needed. + * \retval 1 The configuration tree has been rebuilt. * - * The global configuration files are specified in environment variable ALSA_CONFIG_PATH. + * The global configuration files are specified in the environment variable + * \c ALSA_CONFIG_PATH. * - * Warning: If config tree is reread all the string pointer and config - * node handle previously obtained from this tree become invalid. + * \warning If the configuration tree is reread, all string pointers and + * configuration node handles previously obtained from this tree become invalid. */ int snd_config_update_r(snd_config_t **_top, snd_config_update_t **_update, const char *cfgs) { @@ -2979,16 +3074,17 @@ int snd_config_update_r(snd_config_t **_top, snd_config_update_t **_update, cons static pthread_mutex_t snd_config_update_mutex = PTHREAD_MUTEX_INITIALIZER; /** - * \brief Update #snd_config rereading (if needed) global configuration files. - * \return non-negative value on success, otherwise a negative error code - * \retval 0 no action is needed - * \retval 1 tree has been rebuild + * \brief Updates #snd_config by rereading the global configuration files (if needed). + * \return A non-negative value if successful, otherwise a negative error code. + * \retval 0 No action is needed. + * \retval 1 The configuration tree has been rebuilt. * - * The global configuration files are specified in environment variable ALSA_CONFIG_PATH. - * If it is not set the default value is "/usr/share/alsa/alsa.conf". + * The global configuration files are specified in the environment variable + * \c ALSA_CONFIG_PATH. If this is not set, the default value is + * "/usr/share/alsa/alsa.conf". * - * Warning: If config tree is reread all the string pointer and config - * node handle previously obtained from this tree become invalid. + * \warning If the configuration tree is reread, all string pointers and + * configuration node handles previously obtained from this tree become invalid. */ int snd_config_update(void) { @@ -3001,9 +3097,9 @@ int snd_config_update(void) } /** - * \brief Free private update structure - * \param update private update structure to free - * \return non-negative value on success, otherwise a negative error code + * \brief Frees a private update structure. + * \param update The private update structure to free. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_update_free(snd_config_update_t *update) { @@ -3020,8 +3116,8 @@ int snd_config_update_free(snd_config_update_t *update) } /** - * \brief Free global configuration in snd_config - * \return non-negative value on success, otherwise a negative error code + * \brief Frees the global configuration tree in #snd_config. + * \return Zero if successful, otherwise a negative error code. */ int snd_config_update_free_global(void) { @@ -3037,9 +3133,9 @@ int snd_config_update_free_global(void) } /** - * \brief Return an iterator pointing to first leaf of a compound config node - * \param node Config node handle - * \return iterator value for first leaf + * \brief Returns an iterator pointing to the first child of a compound configuration node. + * \param node Handle to the compound configuration node. + * \return An iterator pointing to the first child. */ snd_config_iterator_t snd_config_iterator_first(const snd_config_t *node) { @@ -3048,9 +3144,12 @@ snd_config_iterator_t snd_config_iterator_first(const snd_config_t *node) } /** - * \brief Return an iterator pointing to next leaf - * \param iterator Config node iterator - * \return iterator value for next leaf + * \brief Returns an iterator pointing to the next sibling. + * \param iterator An iterator pointing to a child configuration node. + * \return An iterator pointing to the next sibling of \p iterator. + * If \p iterator is the last sibling, the returned value is the same + * as the result of calling #snd_config_iterator_end on the father + * of the nodes. */ snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t iterator) { @@ -3058,9 +3157,9 @@ snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t itera } /** - * \brief Return an iterator pointing past the last leaf of a compound config node - * \param node Config node handle - * \return iterator value for end + * \brief Returns an iterator pointing past the last child of a compound configuration node. + * \param node Handle to the compound configuration node. + * \return An iterator pointing past the last child of \p node. */ snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node) { @@ -3069,9 +3168,9 @@ snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node) } /** - * \brief Return the node handle pointed by iterator - * \param iterator Config node iterator - * \return config node handle + * \brief Returns the configuration node handle pointed to by an iterator. + * \param iterator A configuration node iterator. + * \return The configuration node handle pointed to by \p iterator. */ snd_config_t *snd_config_iterator_entry(const snd_config_iterator_t iterator) { @@ -3203,9 +3302,11 @@ static int _snd_config_copy(snd_config_t *src, } /** - * \brief Return the copy of configuration - * \param dst Destination configuration handle - * \return src Source configuration handle + * \brief Creates a copy of a configuration node. + * \param dst The function puts the handle to the new configuration node + * at the address specified by \p dst. + * \param src Handle to the source configuration node. + * \return A non-negative value if successful, otherwise a negative error code. */ int snd_config_copy(snd_config_t **dst, snd_config_t *src) @@ -3402,12 +3503,15 @@ static int _snd_config_evaluate(snd_config_t *src, } /** - * \brief Evaluate a config node in runtime - * \param config source configuration node - * \param root root of the source configuration - * \param private_data private data for runtime evaluation - * \param result result configuration node - * \return zero if success, otherwise a negative error code + * \brief Evaluates a configuration node at runtime. + * \param config Handle to the source configuration node. + * \param root Handle to the root of the source configuration. + * \param private_data Handle to the private data node for runtime evaluation. + * \param result The function puts the handle to the result node at the + * address specified by \p result. \p result is \c NULL for + * in-place evaluation. + * \return A non-negative value if successful, otherwise a negative error code. + * \note Only in-place evaluation is currently implemented. */ int snd_config_evaluate(snd_config_t *config, snd_config_t *root, snd_config_t *private_data, snd_config_t **result) @@ -3801,13 +3905,14 @@ static int parse_args(snd_config_t *subs, const char *str, snd_config_t *defs) } /** - * \brief Expand a node applying arguments and functions - * \param config Config node handle - * \param root Root config node handle - * \param args Arguments string (optional) - * \param private_data Private data for functions - * \param result Pointer to found node - * \return 0 on success otherwise a negative error code + * \brief Expands a configuration node applying arguments and functions. + * \param config Handle to the configuration node. + * \param root Handle to the root configuration node. + * \param args Arguments string (optional). + * \param private_data Handle to the private data node for functions. + * \param result The function puts the handle to the result configuration node + * at the address specified by \p result. + * \return A non-negative value if successful, otherwise a negative error code. */ int snd_config_expand(snd_config_t *config, snd_config_t *root, const char *args, snd_config_t *private_data, snd_config_t **result) @@ -3859,16 +3964,20 @@ int snd_config_expand(snd_config_t *config, snd_config_t *root, const char *args } /** - * \brief Search a definition inside a config tree using alias and expand hooks and arguments - * \param config Config node handle - * \param base Implicit key base (or NULL - none) - * \param key Key suffix - * \param result Pointer to expanded found node - * \return 0 on success otherwise a negative error code + * \brief Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments. + * \param config Handle to the configuration (sub)tree to search. + * \param base Implicit key base, or \c NULL for none. + * \param key Key suffix. + * \param result The function puts the handle to the expanded found node at + * the address specified by \p result. + * \return Zero if successful, otherwise a negative error code. * - * First key is tried and if nothing is found is tried base.key. - * If the value found is a string this is recursively tried in the + * First the key is tried, then, if nothing is found, base.key is tried. + * If the value found is a string, this is recursively tried in the * same way. + * + * If \p key contains a dot (.), the implicit base is ignored and the key + * starts from the root given by \p config. */ int snd_config_search_definition(snd_config_t *config, const char *base, const char *name, diff --git a/src/confmisc.c b/src/confmisc.c index 4562c56d..c6fbe871 100644 --- a/src/confmisc.c +++ b/src/confmisc.c @@ -37,30 +37,30 @@ \section conffunc_ref Function reference
    -
  • The getenv function - snd_func_getenv() - allows to obtain - an environment value. The result is string. -
  • The igetenv function - snd_func_igetenv() - allows to obtain - an environment value. The result is integer. +
  • The getenv function - snd_func_getenv() - obtains + an environment value. The result is a string. +
  • The igetenv function - snd_func_igetenv() - obtains + an environment value. The result is an integer.
  • The concat function - snd_func_concat() - merges all specified - strings. The result is string. + strings. The result is a string.
  • The datadir function - snd_func_datadir() - returns the - data directory. The result is string. + ALSA data directory. The result is a string.
  • The refer function - snd_func_refer() - copies the referred - configuration. The result is same as the referred node. + configuration. The result has the same type as the referred node.
  • The card_driver function - snd_func_card_driver() - returns - the driver identification. The result is string. + a driver identification. The result is a string.
  • The card_id function - snd_func_card_id() - returns - the card identification. The result is string. + a card identification. The result is a string.
  • The pcm_id function - snd_func_pcm_id() - returns - the pcm identification. The result is string. -
  • The private_string - snd_func_private_string() - returns - string using private_data node. -
  • The private_card_driver - snd_func_private_card_driver() - - returns the driver identification using private_data node. - The result is string. -
  • The private_pcm_subdevice - snd_func_private_pcm_subdevice() - - returns the PCM subdevice number using the private_data node. - The result is string. + a pcm identification. The result is a string. +
  • The private_string function - snd_func_private_string() - returns the + string from the private_data node. +
  • The private_card_driver function - snd_func_private_card_driver() - + returns the driver identification from the private_data node. + The result is a string. +
  • The private_pcm_subdevice function - snd_func_private_pcm_subdevice() - + returns the PCM subdevice number from the private_data node. + The result is a string.
*/ @@ -73,9 +73,9 @@ #include "local.h" /** - * \brief Get the boolean value from given ASCII string - * \param ascii The ASCII string to be parsed - * \return a positive value when success otherwise a negative error number + * \brief Gets the boolean value from the given ASCII string. + * \param ascii The string to be parsed. + * \return 0 or 1 if successful, otherwise a negative error code. */ int snd_config_get_bool_ascii(const char *ascii) { @@ -101,9 +101,9 @@ int snd_config_get_bool_ascii(const char *ascii) } /** - * \brief Get the boolean value - * \param conf The configuration node to be parsed - * \return a positive value when success otherwise a negative error number + * \brief Gets the boolean value from a configuration node. + * \param conf Handle to the configuration node to be parsed. + * \return 0 or 1 if successful, otherwise a negative error code. */ int snd_config_get_bool(const snd_config_t *conf) { @@ -135,9 +135,9 @@ int snd_config_get_bool(const snd_config_t *conf) } /** - * \brief Get the control interface index from given ASCII string - * \param ascii The ASCII string to be parsed - * \return a positive value when success otherwise a negative error number + * \brief Gets the control interface index from the given ASCII string. + * \param ascii The string to be parsed. + * \return The control interface index if successful, otherwise a negative error code. */ int snd_config_get_ctl_iface_ascii(const char *ascii) { @@ -158,9 +158,9 @@ int snd_config_get_ctl_iface_ascii(const char *ascii) } /** - * \brief Get the control interface index - * \param conf The configuration node to be parsed - * \return a positive value when success otherwise a negative error number + * \brief Gets the control interface index from a configuration node. + * \param conf Handle to the configuration node to be parsed. + * \return The control interface index if successful, otherwise a negative error code. */ int snd_config_get_ctl_iface(const snd_config_t *conf) { @@ -196,12 +196,14 @@ int snd_config_get_ctl_iface(const snd_config_t *conf) */ /** - * \brief Get environment value - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node, with vars and default definition - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Returns an environment value. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with definitions for \c vars and + * \c default. + * \param private_data Handle to the \c private_data node. + * \return Zero if successful, otherwise a negative error code. * * Example: \code @@ -297,17 +299,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_getenv, SND_CONFIG_DLSYM_VERSION_EVALUATE); #endif /** - * \brief Get integer environment value - * \param dst The destination node (result type is integer) - * \param root The root source node - * \param src The source node, with vars and default definition - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Returns an integer environment value. + * \param dst The function puts the handle to the result configuration node + * (with type integer) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with definitions for \c vars and + * \c default. + * \param private_data Handle to the \c private_data node. + * \return Zero if successful, otherwise a negative error code. * * Example: \code { - @func getenv + @func igetenv vars [ MY_DEVICE DEVICE D ] default 0 } @@ -348,19 +352,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_igetenv, SND_CONFIG_DLSYM_VERSION_EVALUATE); #endif /** - * \brief Merge given strings - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node, with strings definition - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Merges the given strings. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with a definition for \c strings. + * \param private_data Handle to the \c private_data node. + * \return A non-negative value if successful, otherwise a negative error code. * - * Example (result is string "a1b2c3" ]: + * Example (result is "a1b2c3"): \code { @func concat strings [ "a1" "b2" "c3" ] - default 0 } \endcode */ @@ -436,14 +440,15 @@ SND_DLSYM_BUILD_VERSION(snd_func_concat, SND_CONFIG_DLSYM_VERSION_EVALUATE); #endif /** - * \brief Get data directory - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node (unused) - * \return a positive value when success otherwise a negative error number + * \brief Returns the ALSA data directory. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node. + * \param private_data Handle to the \c private_data node. Not used. + * \return A non-negative value if successful, otherwise a negative error code. * - * Example (result is "/usr/share/alsa" using default paths): + * Example (result is "/usr/share/alsa" using the default paths): \code { @func datadir @@ -488,12 +493,14 @@ static int string_from_integer(char **dst, long v) #endif /** - * \brief Get string from private_data - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node (type string, id == "string") - * \return a positive value when success otherwise a negative error number + * \brief Returns the string from \c private_data. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node. + * \param private_data Handle to the \c private_data node (type string, + * id "string"). + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -564,12 +571,14 @@ int snd_determine_driver(int card, char **driver) #endif /** - * \brief Get driver identification using private_data - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node (type = integer, id = "card") - * \return a positive value when success otherwise a negative error number + * \brief Returns the driver identification from \c private_data. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node. + * \param private_data Handle to the \c private_data node (type integer, + * id "card"). + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -609,12 +618,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_card_driver, SND_CONFIG_DLSYM_VERSION_E #endif /** - * \brief Get driver identification - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Returns the driver identification for a card. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with a \c card definition. + * \param private_data Handle to the \c private_data node. + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -666,12 +676,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_driver, SND_CONFIG_DLSYM_VERSION_EVALUATE) #endif /** - * \brief Get card identification - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Returns the identification of a card. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with a \c card definition. + * \param private_data Handle to the \c private_data node. + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -737,12 +748,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_id, SND_CONFIG_DLSYM_VERSION_EVALUATE); #endif /** - * \brief Get pcm identification - * \param dst The destination node (result type is string) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Returns the pcm identification of a device. + * \param dst The function puts the handle to the result configuration node + * (with type string) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with definitions for \c card, + * \c device and (optionally) \c subdevice. + * \param private_data Handle to the \c private_data node. + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -831,12 +844,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_pcm_id, SND_CONFIG_DLSYM_VERSION_EVALUATE); #endif /** - * \brief Get pcm subdevice using private_data - * \param dst The destination node (result type is integer) - * \param root The root source node - * \param src The source node - * \param private_data The private_data node (type = pointer, id = "pcm_handle") - * \return a positive value when success otherwise a negative error number + * \brief Returns the PCM subdevice from \c private_data. + * \param dst The function puts the handle to the result configuration node + * (with type integer) at the address specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node. + * \param private_data Handle to the \c private_data node (type pointer, + * id "pcm_handle"). + * \return A non-negative value if successful, otherwise a negative error code. * * Example: \code @@ -881,12 +896,16 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_pcm_subdevice, SND_CONFIG_DLSYM_VERSION #endif /** - * \brief Copy the referred configuration node - * \param dst The destination node (result type is same as referred node) - * \param root The root source node (can be modified!!!) - * \param src The source node - * \param private_data The private_data node - * \return a positive value when success otherwise a negative error number + * \brief Copies the specified configuration node. + * \param dst The function puts the handle to the result configuration node + * (with the same type as the specified node) at the address + * specified by \p dst. + * \param root Handle to the root source node. + * \param src Handle to the source node, with definitions for \c name and + * (optionally) \c file. + * \param private_data Handle to the \c private_data node. + * \return A non-negative value if successful, otherwise a negative error code. + * \note The root source node can be modified! * * Example: \code diff --git a/src/dlmisc.c b/src/dlmisc.c index 328e20c4..ed749d3f 100644 --- a/src/dlmisc.c +++ b/src/dlmisc.c @@ -37,13 +37,13 @@ struct snd_dlsym_link *snd_dlsym_start = NULL; #endif /** - * \brief Open the dynamic library, with ALSA extension - * \param name name, similar to dlopen - * \param mode mode, similar to dlopen - * \return pointer to handle + * \brief Opens a dynamic library - ALSA wrapper for \c dlopen. + * \param name name of the library, similar to \c dlopen. + * \param mode mode flags, similar to \c dlopen. + * \return Library handle if successful, otherwise \c NULL. * - * The extension is a special code for the static build of - * the alsa-lib library. + * This function can emulate dynamic linking for the static build of + * the alsa-lib library. In that case, \p name is set to \c NULL. */ void *snd_dlopen(const char *name, int mode) { @@ -55,11 +55,11 @@ void *snd_dlopen(const char *name, int mode) } /** - * \brief Close the dynamic library, with ALSA extension - * \param handle handle, similar to dlclose - * \return zero if success, otherwise an error code + * \brief Closes a dynamic library - ALSA wrapper for \c dlclose. + * \param handle Library handle, similar to \c dlclose. + * \return Zero if successful, otherwise an error code. * - * The extension is a special code for the static build of + * This function can emulate dynamic linking for the static build of * the alsa-lib library. */ int snd_dlclose(void *handle) @@ -72,11 +72,14 @@ int snd_dlclose(void *handle) } /** - * \brief Verify dynamically loaded symbol - * \param handle dlopen handle - * \param name name of symbol - * \param version version of symbol - * \return zero is success, otherwise a negative error code + * \brief Verifies a dynamically loaded symbol. + * \param handle Library handle, similar to \c dlsym. + * \param name Symbol name. + * \param version Version of the symbol. + * \return Zero is successful, otherwise a negative error code. + * + * This function checks that the symbol with the version appended to its name + * does exist in the library. */ static int snd_dlsym_verify(void *handle, const char *name, const char *version) { @@ -99,14 +102,17 @@ static int snd_dlsym_verify(void *handle, const char *name, const char *version) } /** - * \brief Resolve the symbol, with ALSA extension - * \param handle handle, similar to dlsym - * \param name symbol name - * \param version symbol version + * \brief Resolves a symbol from a dynamic library - ALSA wrapper for \c dlsym. + * \param handle Library handle, similar to \c dlsym. + * \param name Symbol name. + * \param version Version of the symbol. + * + * This function can emulate dynamic linking for the static build of + * the alsa-lib library. * - * This special version of dlsym function checks also - * the version of symbol. The version of a symbol should - * be defined using #SND_DLSYM_BUILD_VERSION macro. + * This special version of the \c dlsym function checks also the version + * of the symbol. A versioned symbol should be defined using the + * #SND_DLSYM_BUILD_VERSION macro. */ void *snd_dlsym(void *handle, const char *name, const char *version) { diff --git a/src/error.c b/src/error.c index 184a7034..0b52a7e8 100644 --- a/src/error.c +++ b/src/error.c @@ -43,10 +43,10 @@ static const char *snd_error_codes[] = }; /** - * \brief Get the error string. - * \param errnum The error code number. - * - * Returns the ASCII description of the given numeric error code. + * \brief Returns the message for an error code. + * \param errnum The error code number, which must be a system error code + * or an ALSA error code. + * \return The ASCII description of the given numeric error code. */ const char *snd_strerror(int errnum) { @@ -65,11 +65,11 @@ const char *snd_strerror(int errnum) * \param file The filename where the error was hit. * \param line The line number. * \param function The function name. - * \param err The error number. + * \param err The error code. * \param fmt The message (including the format characters). * \param ... Optional arguments. * - * Prints the error message including location to stderr. + * Prints the error message including location to \c stderr. */ static void snd_lib_error_default(const char *file, int line, const char *function, int err, const char *fmt, ...) { @@ -86,17 +86,18 @@ static void snd_lib_error_default(const char *file, int line, const char *functi /** * \ingroup Error * Pointer to the error handler function. + * For internal use only. */ -snd_lib_error_handler_t *snd_lib_error = snd_lib_error_default; +snd_lib_error_handler_t snd_lib_error = snd_lib_error_default; /** - * \brief Set the error handler. + * \brief Sets the error handler. * \param handler The pointer to the new error handler function. * - * This function sets a new error handler or the default one (if the NULL - * parameter is given) which prints the error messages to stderr. + * This function sets a new error handler, or (if \c handler is \c NULL) + * the default one which prints the error messages to \c stderr. */ -int snd_lib_error_set_handler(snd_lib_error_handler_t *handler) +int snd_lib_error_set_handler(snd_lib_error_handler_t handler) { snd_lib_error = handler == NULL ? snd_lib_error_default : handler; return 0; diff --git a/src/input.c b/src/input.c index 7ded1ee5..35d7e068 100644 --- a/src/input.c +++ b/src/input.c @@ -51,9 +51,9 @@ struct _snd_input { #endif /** - * \brief close input handle - * \param input Input handle - * \return 0 on success otherwise a negative error code + * \brief Closes an input handle. + * \param input The input handle to be closed. + * \return Zero if successful, otherwise a negative error code. */ int snd_input_close(snd_input_t *input) { @@ -63,11 +63,13 @@ int snd_input_close(snd_input_t *input) } /** - * \brief fscanf(3) like on an input handle - * \param input Input handle - * \param format fscanf format - * \param ... other fscanf arguments - * \return number of input items assigned otherwise a negative error code + * \brief Reads formatted input (like \c fscanf(3)) from an input handle. + * \param input The input handle. + * \param format Format string in \c fscanf format. + * \param ... Other \c fscanf arguments. + * \return The number of input items assigned, or \c EOF. + * + * \bug Reading from a memory buffer doesn't work. */ int snd_input_scanf(snd_input_t *input, const char *format, ...) { @@ -80,11 +82,14 @@ int snd_input_scanf(snd_input_t *input, const char *format, ...) } /** - * \brief fgets(3) like on an input handle - * \param input Input handle - * \param str Destination buffer pointer - * \param size Buffer size - * \return Pointer to buffer or NULL on error + * \brief Reads a line from an input handle (like \c fgets(3)). + * \param input The input handle. + * \param str Address of the destination buffer. + * \param size The size of the destination buffer. + * \return Pointer to the buffer if successful, otherwise \c NULL. + * + * Like \c fgets, the returned string is zero-terminated, and contains + * the new-line character \c '\n' if the line fits into the buffer. */ char *snd_input_gets(snd_input_t *input, char *str, size_t size) { @@ -92,9 +97,9 @@ char *snd_input_gets(snd_input_t *input, char *str, size_t size) } /** - * \brief fgetc(3) like on an input handle - * \param input Input handle - * \return character read or EOF on end of file or error + * \brief Reads a character from an input handle (like \c fgetc(3)). + * \param input The input handle. + * \return The character read, or \c EOF on end of file or error. */ int snd_input_getc(snd_input_t *input) { @@ -102,10 +107,10 @@ int snd_input_getc(snd_input_t *input) } /** - * \brief ungetc(3) like on an input handle - * \param input Input handle - * \param c Char to push back - * \return character pushed back or EOF on error + * \brief Puts the last character read back to an input handle (like \c ungetc(3)). + * \param input The input handle. + * \param c The character to push back. + * \return The character pushed back, or \c EOF on error. */ int snd_input_ungetc(snd_input_t *input, int c) { @@ -162,11 +167,14 @@ static snd_input_ops_t snd_input_stdio_ops = { #endif /** - * \brief Create a new input using an existing stdio FILE pointer - * \param inputp Pointer to returned input handle - * \param fp FILE pointer - * \param close Close flag (1 if FILE is fclose'd when input handle is closed) - * \return 0 on success otherwise a negative error code + * \brief Creates a new input object using an existing stdio \c FILE pointer. + * \param inputp The function puts the pointer to the new input object + * at the address specified by \p inputp. + * \param fp The \c FILE pointer to read from. + * Reading begins at the current file position. + * \param close Close flag. Set this to 1 if #snd_input_close should close + * \p fp by calling \c fclose. + * \return Zero if successful, otherwise a negative error code. */ int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close) { @@ -191,11 +199,12 @@ int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close) } /** - * \brief Open a new input from a file - * \param inputp Pointer to returned input handle - * \param file File name - * \param mode fopen(3) open mode - * \return 0 on success otherwise a negative error code + * \brief Creates a new input object reading from a file. + * \param inputp The functions puts the pointer to the new input object + * at the address specified by \p inputp. + * \param file The name of the file to read from. + * \param mode The open mode, like \c fopen(3). + * \return Zero if successful, otherwise a negative error code. */ int snd_input_stdio_open(snd_input_t **inputp, const char *file, const char *mode) { @@ -284,11 +293,15 @@ static snd_input_ops_t snd_input_buffer_ops = { #endif /** - * \brief Open a new input from a memory buffer - * \param inputp Pointer to returned input handle - * \param buf Buffer pointer - * \param size Buffer size - * \return 0 on success otherwise a negative error code + * \brief Creates a new input object from a memory buffer. + * \param inputp The function puts the pointer to the new input object + * at the address specified by \p inputp. + * \param buf Address of the input buffer. + * \param size Size of the input buffer. + * \return Zero if successful, otherwise a negative error code. + * + * This functions creates a copy of the input buffer, so the application is + * not required to preserve the buffer after this function has been called. */ int snd_input_buffer_open(snd_input_t **inputp, const char *buf, ssize_t size) { diff --git a/src/output.c b/src/output.c index 2730d766..2804b20f 100644 --- a/src/output.c +++ b/src/output.c @@ -50,9 +50,9 @@ struct _snd_output { #endif /** - * \brief close output handle - * \param output Output handle - * \return 0 on success otherwise a negative error code + * \brief Closes an output handle. + * \param output The output handle to be closed. + * \return Zero if successful, otherwise a negative error code. */ int snd_output_close(snd_output_t *output) { @@ -62,11 +62,11 @@ int snd_output_close(snd_output_t *output) } /** - * \brief fprintf(3) like on an output handle - * \param output Output handle - * \param format fprintf format - * \param ... other fprintf arguments - * \return number of characters written otherwise a negative error code + * \brief Writes formatted output (like \c fprintf(3)) to an output handle. + * \param output The output handle. + * \param format Format string in \c fprintf format. + * \param ... Other \c fprintf arguments. + * \return The number of characters written, or a negative error code. */ int snd_output_printf(snd_output_t *output, const char *format, ...) { @@ -79,10 +79,10 @@ int snd_output_printf(snd_output_t *output, const char *format, ...) } /** - * \brief fputs(3) like on an output handle - * \param output Output handle - * \param str Buffer pointer - * \return 0 on success otherwise a negative error code + * \brief Writes a string to an output handle (like \c fputs(3)). + * \param output The output handle. + * \param str Pointer to the string. + * \return Zero if successful, otherwise a negative error code or \c EOF. */ int snd_output_puts(snd_output_t *output, const char *str) { @@ -90,10 +90,10 @@ int snd_output_puts(snd_output_t *output, const char *str) } /** - * \brief fputs(3) like on an output handle - * \param output Output handle - * \param str Source buffer pointer - * \return 0 on success otherwise a negative error code + * \brief Writes a character to an output handle (like \c putc(3)). + * \param output The output handle. + * \param c The character. + * \return Zero if successful, otherwise a negative error code or \c EOF. */ int snd_output_putc(snd_output_t *output, int c) { @@ -101,9 +101,13 @@ int snd_output_putc(snd_output_t *output, int c) } /** - * \brief fflush(3) like on an output handle - * \param output Output handle - * \return 0 on success otherwise a negative error code + * \brief Flushes an output handle (like fflush(3)). + * \param output The output handle. + * \return Zero if successful, otherwise \c EOF. + * + * If the underlying destination is a stdio stream, this function calls + * \c fflush. If the underlying destination is a memory buffer, the write + * position is reset to the beginning of the buffer. \c =:-o */ int snd_output_flush(snd_output_t *output) { @@ -160,11 +164,14 @@ static snd_output_ops_t snd_output_stdio_ops = { #endif /** - * \brief Create a new output using an existing stdio FILE pointer - * \param outputp Pointer to returned output handle - * \param fp FILE pointer - * \param close Close flag (1 if FILE is fclose'd when output handle is closed) - * \return 0 on success otherwise a negative error code + * \brief Creates a new output object using an existing stdio \c FILE pointer. + * \param outputp The function puts the pointer to the new output object + * at the address specified by \p outputp. + * \param fp The \c FILE pointer to write to. Characters are written + * to the file starting at the current file position. + * \param close Close flag. Set this to 1 if #snd_output_close should close + * \p fp by calling \c fclose. + * \return Zero if successful, otherwise a negative error code. */ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close) { @@ -189,11 +196,12 @@ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close) } /** - * \brief Open a new output to a file - * \param outputp Pointer to returned output handle - * \param file File name - * \param mode fopen(3) open mode - * \return 0 on success otherwise a negative error code + * \brief Creates a new output object writing to a file. + * \param outputp The function puts the pointer to the new output object + * at the address specified by \p outputp. + * \param file The name of the file to open. + * \param mode The open mode, like \c fopen(3). + * \return Zero if successful, otherwise a negative error code. */ int snd_output_stdio_open(snd_output_t **outputp, const char *file, const char *mode) { @@ -307,10 +315,14 @@ static snd_output_ops_t snd_output_buffer_ops = { #endif /** - * \brief Return buffer info for a #SND_OUTPUT_TYPE_BUFFER output handle - * \param output Output handle - * \param buf Pointer to returned buffer - * \return size of data in buffer + * \brief Returns the address of the buffer of a #SND_OUTPUT_TYPE_BUFFER output handle. + * \param output The output handle. + * \param buf The functions puts the current address of the buffer at the + * address specified by \p buf. + * \return The current size of valid data in the buffer. + * + * The address of the buffer may become invalid when output functions or + * #snd_output_close are called. */ size_t snd_output_buffer_string(snd_output_t *output, char **buf) { @@ -320,9 +332,10 @@ size_t snd_output_buffer_string(snd_output_t *output, char **buf) } /** - * \brief Open a new output to an auto extended memory buffer - * \param outputp Pointer to returned output handle - * \return 0 on success otherwise a negative error code + * \brief Creates a new output object with an auto-extending memory buffer. + * \param outputp The function puts the pointer to the new output object + * at the address specified by \p outputp. + * \return Zero if successful, otherwise a negative error code. */ int snd_output_buffer_open(snd_output_t **outputp) { -- 2.47.1