<H2>Preface</H2>
<P>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.</P>
<H2>Documentation License</H2>
<P>This documentation is free; you can redistribute it without
-any restrictions. The modification or derived work must retain
-copyright and list all authors.</P>
+any restrictions. Modifications or derived work must retain
+the copyright and list all authors.</P>
<P>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.</P>
<H2>API usage</H2>
-<P>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
+<P>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.</P>
<H2>API links</H2>
<UL>
- <LI>Page \ref control explains the primitive controls API
- <LI>Page \ref hcontrol explains the high-level primitive controls API
- <LI>Page \ref pcm explains the design of PCM (digital audio) API
- <LI>Page \ref pcm_plugins explains the design of PCM (digital audio) plugins
- <LI>Page \ref rawmidi explains the design of RawMidi API
- <LI>Page \ref timer explains the design of Timer API
- <LI>Page \ref seq explains the design of Sequencer API
+ <LI>Page \ref control explains the primitive controls API.
+ <LI>Page \ref hcontrol explains the high-level primitive controls API.
+ <LI>Page \ref pcm explains the design of the PCM (digital audio) API.
+ <LI>Page \ref pcm_plugins explains the design of PCM (digital audio) plugins.
+ <LI>Page \ref rawmidi explains the design of the RawMidi API.
+ <LI>Page \ref timer explains the design of the Timer API.
+ <LI>Page \ref seq explains the design of the Sequencer API.
</UL>
<H2>Configuration</H2>
<UL>
<LI>Page \ref conf explains the syntax of library configuration files.
<LI>Page \ref confarg explains the run-time argument syntax.
- <LI>Page \ref conffunc explains the run-time function definition and usage.
- <LI>Page \ref confhooks explains the run-time hooks definition and usage.
+ <LI>Page \ref conffunc explains run-time function definitions and their usage.
+ <LI>Page \ref confhooks explains run-time hook definitions and their usage.
</UL>
*/
* \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
#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.
* \{
*/
#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 */
#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 */
#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 */
/** \} */
/**
- * \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 */
#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 */
#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 */
#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 */
* \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
/**
* \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;
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))
* \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
/**
* \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)
/** \} */
* \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
/**
* \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
/** \} */
/**
* \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.
* \{
*/
#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 */
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)); \
#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);
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,
* \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
/**
* \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;
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);
* \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
/**
* \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;
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);
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
/*! \page conf Configuration files
-<P>Configuration files are using a simple format allowing the modern
+<P>Configuration files use a simple format allowing modern
data description like nesting and array assignments.</P>
\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
\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
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 \
\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 <filename> syntax. The global
-configuration directory can be referenced using <confdir:filename> syntax.
+To include another configuration file, write the file name in angle brackets.
+The prefix \c confdir: will reference the global configuration directory.
\code
</etc/alsa1.conf>
\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
\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 [
]
\endcode
-Above code is equal to
+The above code is equal to
\code
a.0 "first"
\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;
\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
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
a 1,
\endcode
-\subsection conf_compound Compound assign (definition using braces)
+\subsection conf_compound Compound assignments (definitions using braces)
\code
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 [
]
\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
# Include a new configuration file
<filename>
-# 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
*/
-/*! \page confarg Configuration - runtime arguments
+/*! \page confarg Runtime arguments in configuration files
<P>The ALSA library can accept runtime arguments for some configuration
-blocks. This extension is on top of the basic syntax of the configuration
+blocks. This extension is built on top of the basic configuration file
\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 {
}
\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
\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
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
*/
-/*! \page conffunc Configuration - runtime functions
+/*! \page conffunc Runtime functions in configuration files
-<P>The ALSA library accepts the runtime modification of configuration.
-The several build-in functions are available.</P>
+<P>The ALSA library can modify the configuration at runtime.
+Several built-in functions are available.</P>
-<P>The function is referred using id @func and function name. All other
+<P>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.<function_name> 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:</P>
+If the compound func.<function_name> 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:</P>
\code
func.remove_first_char {
*/
-/*! \page confhooks Configuration - hooks
+/*! \page confhooks Hooks in configuration files
-<P>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.</P>
+<P>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.</P>
-<P>The example definition a hook which loads two configuration files at beginning:</P>
+<P>This example defines a hook which loads two configuration files at the
+beginning:</P>
\code
@hooks [
\section confhooks_ref Function reference
<UL>
- <LI>The function load - snd_config_hook_load() - loads and parses the given
- configuration files.
- <LI>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.
+ <LI>The function load - \c snd_config_hook_load() - loads and parses the
+ given configuration files.
+ <LI>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.
</UL>
*/
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;
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
#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)
{
}
/**
- * \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)
{
}
/**
- * \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, ...)
{
}
/**
- * \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, ...)
{
}
/**
- * \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,
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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, ...)
}
/**
- * \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,
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 {
}
/**
- * \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)
{
#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)
{
#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)
{
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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
}
/**
- * \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)
}
/**
- * \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)
}
/**
- * \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,
\section conffunc_ref Function reference
<UL>
- <LI>The getenv function - snd_func_getenv() - allows to obtain
- an environment value. The result is string.
- <LI>The igetenv function - snd_func_igetenv() - allows to obtain
- an environment value. The result is integer.
+ <LI>The getenv function - snd_func_getenv() - obtains
+ an environment value. The result is a string.
+ <LI>The igetenv function - snd_func_igetenv() - obtains
+ an environment value. The result is an integer.
<LI>The concat function - snd_func_concat() - merges all specified
- strings. The result is string.
+ strings. The result is a string.
<LI>The datadir function - snd_func_datadir() - returns the
- data directory. The result is string.
+ ALSA data directory. The result is a string.
<LI>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.
<LI>The card_driver function - snd_func_card_driver() - returns
- the driver identification. The result is string.
+ a driver identification. The result is a string.
<LI>The card_id function - snd_func_card_id() - returns
- the card identification. The result is string.
+ a card identification. The result is a string.
<LI>The pcm_id function - snd_func_pcm_id() - returns
- the pcm identification. The result is string.
- <LI>The private_string - snd_func_private_string() - returns
- string using private_data node.
- <LI>The private_card_driver - snd_func_private_card_driver() -
- returns the driver identification using private_data node.
- The result is string.
- <LI>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.
+ <LI>The private_string function - snd_func_private_string() - returns the
+ string from the private_data node.
+ <LI>The private_card_driver function - snd_func_private_card_driver() -
+ returns the driver identification from the private_data node.
+ The result is a string.
+ <LI>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.
</UL>
*/
#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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
*/
/**
- * \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
#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
}
#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
*/
#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
#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
#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
#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
#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
#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
#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
#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
#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)
{
}
/**
- * \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)
}
/**
- * \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)
{
}
/**
- * \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)
{
};
/**
- * \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)
{
* \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, ...)
{
/**
* \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;
#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)
{
}
/**
- * \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, ...)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
#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)
{
}
/**
- * \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)
{
#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)
{
#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)
{
}
/**
- * \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, ...)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
}
/**
- * \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)
{
#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)
{
}
/**
- * \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)
{
#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)
{
}
/**
- * \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)
{
git://git.alsa-project.org / alsa-lib.git / commitdiff