mirrors/alsa-lib
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-lib.git synced 2025-10-29 05:40:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Documentation update by Clement Ladish

Browse source
This commit is contained in:
Jaroslav Kysela 2002-07-23 19:51:16 +00:00
parent 2db6b18b39
commit 63d708a344
15 changed files with 965 additions and 714 deletions
Download patch file Download diff file Expand all files Collapse all files

32
doc/index.doxygen
View file

@ -7,36 +7,36 @@
<H2>Preface</H2> <H2>Preface</H2>
<P>The Advanced Linux Sound Architecture (\e ALSA) comes with a kernel <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> it interfaces with the kernel API.</P>
<H2>Documentation License</H2> <H2>Documentation License</H2>
<P>This documentation is free; you can redistribute it without <P>This documentation is free; you can redistribute it without
any restrictions. The modification or derived work must retain any restrictions. Modifications or derived work must retain
copyright and list all authors.</P> the copyright and list all authors.</P>
<P>This documentation is distributed in the hope that it will be <P>This documentation is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
<H2>API usage</H2> <H2>API usage</H2>
<P>Application programmers should use the library API rather than <P>Application programmers should use the library API rather than the
kernel API. The library offers 100% of the functionally of the kernel API, kernel API. The library offers 100% of the functionality of the kernel API,
but add major improvements in usability, making the application code simpler but adds major improvements in usability, making the application code simpler
and better looking. In addition, some of the some fixes/compatibility code and better looking. In addition, future fixes or compatibility code
may be placed in the library code instead of the kernel driver.</P> may be placed in the library code instead of the kernel driver.</P>
<H2>API links</H2> <H2>API links</H2>
<UL> <UL>
<LI>Page \ref control explains the primitive controls API <LI>Page \ref control explains the primitive controls API.
<LI>Page \ref hcontrol explains the high-level 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 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 pcm_plugins explains the design of PCM (digital audio) plugins.
<LI>Page \ref rawmidi explains the design of RawMidi API <LI>Page \ref rawmidi explains the design of the RawMidi API.
<LI>Page \ref timer explains the design of Timer API <LI>Page \ref timer explains the design of the Timer API.
<LI>Page \ref seq explains the design of Sequencer API <LI>Page \ref seq explains the design of the Sequencer API.
</UL> </UL>
<H2>Configuration</H2> <H2>Configuration</H2>
@ -44,8 +44,8 @@ may be placed in the library code instead of the kernel driver.</P>
<UL> <UL>
<LI>Page \ref conf explains the syntax of library configuration files. <LI>Page \ref conf explains the syntax of library configuration files.
<LI>Page \ref confarg explains the run-time argument syntax. <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 conffunc explains run-time function definitions and their usage.
<LI>Page \ref confhooks explains the run-time hooks definition and usage. <LI>Page \ref confhooks explains run-time hook definitions and their usage.
</UL> </UL>
*/ */

62
include/asoundef.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Definitions of constants for the ALSA driver * Definitions of constants for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -33,8 +33,8 @@ extern "C" {
#endif #endif
/** /**
* \defgroup Digital_Audio_Interface Constants For Digital Audio Interface * \defgroup Digital_Audio_Interface Constants for Digital Audio Interfaces
* AES/IEC958 channel status bits * AES/IEC958 channel status bits.
* \{ * \{
*/ */
@ -42,7 +42,7 @@ extern "C" {
#define IEC958_AES0_NONAUDIO (1<<1) /**< 0 = audio, 1 = non-audio */ #define IEC958_AES0_NONAUDIO (1<<1) /**< 0 = audio, 1 = non-audio */
#define IEC958_AES0_PRO_EMPHASIS (7<<2) /**< mask - emphasis */ #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_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_5015 (3<<2) /**< 50/15us emphasis */
#define IEC958_AES0_PRO_EMPHASIS_CCITT (7<<2) /**< CCITT J.17 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_FREQ_UNLOCKED (1<<5) /**< source sample frequency: 0 = locked, 1 = unlocked */
@ -53,18 +53,18 @@ extern "C" {
#define IEC958_AES0_PRO_FS_32000 (3<<6) /**< 32kHz */ #define IEC958_AES0_PRO_FS_32000 (3<<6) /**< 32kHz */
#define IEC958_AES0_CON_NOT_COPYRIGHT (1<<2) /**< 0 = copyright, 1 = not copyright */ #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 (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_EMPHASIS_5015 (1<<3) /**< 50/15us emphasis */
#define IEC958_AES0_CON_MODE (3<<6) /**< mask - mode */ #define IEC958_AES0_CON_MODE (3<<6) /**< mask - mode */
#define IEC958_AES1_PRO_MODE (15<<0) /**< mask - channel 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_STEREOPHONIC (2<<0) /**< stereophonic - ch A is left */
#define IEC958_AES1_PRO_MODE_SINGLE (4<<0) /**< single channel */ #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_TWO (8<<0) /**< two channels */
#define IEC958_AES1_PRO_MODE_PRIMARY (12<<0) /**< primary/secondary */ #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_MODE_BYTE3 (15<<0) /**< vector to byte 3 */
#define IEC958_AES1_PRO_USERBITS (15<<4) /**< mask - user bits */ #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_192 (8<<4) /**< 192-bit structure */
#define IEC958_AES1_PRO_USERBITS_UDEF (12<<4) /**< user defined application */ #define IEC958_AES1_PRO_USERBITS_UDEF (12<<4) /**< user defined application */
#define IEC958_AES1_CON_CATEGORY 0x7f /**< consumer category */ #define IEC958_AES1_CON_CATEGORY 0x7f /**< consumer category */
@ -104,15 +104,15 @@ extern "C" {
#define IEC958_AES2_PRO_SBITS_24 (4<<0) /**< 24-bit - main audio */ #define IEC958_AES2_PRO_SBITS_24 (4<<0) /**< 24-bit - main audio */
#define IEC958_AES2_PRO_SBITS_UDEF (6<<0) /**< user defined application */ #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 (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_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_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_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_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 (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 (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 (15<<0) /**< mask - sample frequency */
#define IEC958_AES3_CON_FS_44100 (0<<0) /**< 44.1kHz */ #define IEC958_AES3_CON_FS_44100 (0<<0) /**< 44.1kHz */
#define IEC958_AES3_CON_FS_48000 (2<<0) /**< 48kHz */ #define IEC958_AES3_CON_FS_48000 (2<<0) /**< 48kHz */
@ -125,32 +125,32 @@ extern "C" {
/** \} */ /** \} */
/** /**
* \defgroup MIDI_Interface Constants For MIDI v1.0 Interface * \defgroup MIDI_Interface Constants for MIDI v1.0
* Constants for MIDI v1.0 interface * Constants for MIDI v1.0.
* \{ * \{
*/ */
#define MIDI_CHANNELS 16 /**< number of channels */ #define MIDI_CHANNELS 16 /**< Number of channels per port/cable. */
#define MIDI_GM_DRUM_CHANNEL (10-1) /**< channel number for GM drum */ #define MIDI_GM_DRUM_CHANNEL (10-1) /**< Channel number for GM drums. */
/** /**
* \defgroup MIDI_Commands MIDI Commands * \defgroup MIDI_Commands MIDI Commands
* MIDI Commands * MIDI command codes.
* \{ * \{
*/ */
#define MIDI_CMD_NOTE_OFF 0x80 /**< note-off */ #define MIDI_CMD_NOTE_OFF 0x80 /**< note off */
#define MIDI_CMD_NOTE_ON 0x90 /**< note-on */ #define MIDI_CMD_NOTE_ON 0x90 /**< note on */
#define MIDI_CMD_NOTE_PRESSURE 0xa0 /**< key-pressure */ #define MIDI_CMD_NOTE_PRESSURE 0xa0 /**< key pressure */
#define MIDI_CMD_CONTROL 0xb0 /**< MIDI control */ #define MIDI_CMD_CONTROL 0xb0 /**< control change */
#define MIDI_CMD_PGM_CHANGE 0xc0 /**< program change */ #define MIDI_CMD_PGM_CHANGE 0xc0 /**< program change */
#define MIDI_CMD_CHANNEL_PRESSURE 0xd0 /**< channel-pressure */ #define MIDI_CMD_CHANNEL_PRESSURE 0xd0 /**< channel pressure */
#define MIDI_CMD_BENDER 0xe0 /**< pitch-bender */ #define MIDI_CMD_BENDER 0xe0 /**< pitch bender */
#define MIDI_CMD_COMMON_SYSEX 0xf0 /**< sysex (system exclusive) begin */ #define MIDI_CMD_COMMON_SYSEX 0xf0 /**< sysex (system exclusive) begin */
#define MIDI_CMD_COMMON_MTC_QUARTER 0xf1 /**< MTC quarter frame */ #define MIDI_CMD_COMMON_MTC_QUARTER 0xf1 /**< MTC quarter frame */
#define MIDI_CMD_COMMON_SONG_POS 0xf2 /**< song position */ #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_TUNE_REQUEST 0xf6 /**< tune request */
#define MIDI_CMD_COMMON_SYSEX_END 0xf7 /**< end of sysex */ #define MIDI_CMD_COMMON_SYSEX_END 0xf7 /**< end of sysex */
#define MIDI_CMD_COMMON_CLOCK 0xf8 /**< clock */ #define MIDI_CMD_COMMON_CLOCK 0xf8 /**< clock */
@ -158,25 +158,25 @@ extern "C" {
#define MIDI_CMD_COMMON_CONTINUE 0xfb /**< continue */ #define MIDI_CMD_COMMON_CONTINUE 0xfb /**< continue */
#define MIDI_CMD_COMMON_STOP 0xfc /**< stop */ #define MIDI_CMD_COMMON_STOP 0xfc /**< stop */
#define MIDI_CMD_COMMON_SENSING 0xfe /**< active sensing */ #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 * \defgroup MIDI_Controllers MIDI Controllers
* MIDI Controllers * MIDI controller numbers.
* \{ * \{
*/ */
#define MIDI_CTL_MSB_BANK 0x00 /**< Bank selection */ #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_BREATH 0x02 /**< Breath */
#define MIDI_CTL_MSB_FOOT 0x04 /**< Foot */ #define MIDI_CTL_MSB_FOOT 0x04 /**< Foot */
#define MIDI_CTL_MSB_PORTAMENTO_TIME 0x05 /**< Portamento time */ #define MIDI_CTL_MSB_PORTAMENTO_TIME 0x05 /**< Portamento time */
#define MIDI_CTL_MSB_DATA_ENTRY 0x06 /**< Data entry */ #define MIDI_CTL_MSB_DATA_ENTRY 0x06 /**< Data entry */
#define MIDI_CTL_MSB_MAIN_VOLUME 0x07 /**< Main volume */ #define MIDI_CTL_MSB_MAIN_VOLUME 0x07 /**< Main volume */
#define MIDI_CTL_MSB_BALANCE 0x08 /**< Balance */ #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_EXPRESSION 0x0b /**< Expression */
#define MIDI_CTL_MSB_EFFECT1 0x0c /**< Effect1 */ #define MIDI_CTL_MSB_EFFECT1 0x0c /**< Effect1 */
#define MIDI_CTL_MSB_EFFECT2 0x0d /**< Effect2 */ #define MIDI_CTL_MSB_EFFECT2 0x0d /**< Effect2 */
@ -185,14 +185,14 @@ extern "C" {
#define MIDI_CTL_MSB_GENERAL_PURPOSE3 0x12 /**< General purpose 3 */ #define MIDI_CTL_MSB_GENERAL_PURPOSE3 0x12 /**< General purpose 3 */
#define MIDI_CTL_MSB_GENERAL_PURPOSE4 0x13 /**< General purpose 4 */ #define MIDI_CTL_MSB_GENERAL_PURPOSE4 0x13 /**< General purpose 4 */
#define MIDI_CTL_LSB_BANK 0x20 /**< Bank selection */ #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_BREATH 0x22 /**< Breath */
#define MIDI_CTL_LSB_FOOT 0x24 /**< Foot */ #define MIDI_CTL_LSB_FOOT 0x24 /**< Foot */
#define MIDI_CTL_LSB_PORTAMENTO_TIME 0x25 /**< Portamento time */ #define MIDI_CTL_LSB_PORTAMENTO_TIME 0x25 /**< Portamento time */
#define MIDI_CTL_LSB_DATA_ENTRY 0x26 /**< Data entry */ #define MIDI_CTL_LSB_DATA_ENTRY 0x26 /**< Data entry */
#define MIDI_CTL_LSB_MAIN_VOLUME 0x27 /**< Main volume */ #define MIDI_CTL_LSB_MAIN_VOLUME 0x27 /**< Main volume */
#define MIDI_CTL_LSB_BALANCE 0x28 /**< Balance */ #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_EXPRESSION 0x2b /**< Expression */
#define MIDI_CTL_LSB_EFFECT1 0x2c /**< Effect1 */ #define MIDI_CTL_LSB_EFFECT1 0x2c /**< Effect1 */
#define MIDI_CTL_LSB_EFFECT2 0x2d /**< Effect2 */ #define MIDI_CTL_LSB_EFFECT2 0x2d /**< Effect2 */
@ -200,9 +200,9 @@ extern "C" {
#define MIDI_CTL_LSB_GENERAL_PURPOSE2 0x31 /**< General purpose 2 */ #define MIDI_CTL_LSB_GENERAL_PURPOSE2 0x31 /**< General purpose 2 */
#define MIDI_CTL_LSB_GENERAL_PURPOSE3 0x32 /**< General purpose 3 */ #define MIDI_CTL_LSB_GENERAL_PURPOSE3 0x32 /**< General purpose 3 */
#define MIDI_CTL_LSB_GENERAL_PURPOSE4 0x33 /**< General purpose 4 */ #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_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_SOFT_PEDAL 0x43 /**< Soft pedal */
#define MIDI_CTL_LEGATO_FOOTSWITCH 0x44 /**< Legato foot switch */ #define MIDI_CTL_LEGATO_FOOTSWITCH 0x44 /**< Legato foot switch */
#define MIDI_CTL_HOLD2 0x45 /**< Hold2 */ #define MIDI_CTL_HOLD2 0x45 /**< Hold2 */

57
include/conf.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Application interface library for the ALSA driver * Application interface library for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -34,36 +34,52 @@ extern "C" {
/** /**
* \defgroup Config Configuration Interface * \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 #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 #define SND_CONFIG_DLSYM_VERSION_HOOK _dlsym_config_hook_001
/** Config node type */ /** Configuration node type. */
typedef enum _snd_config_type { typedef enum _snd_config_type {
/** Integer number */ /** Integer number. */
SND_CONFIG_TYPE_INTEGER, SND_CONFIG_TYPE_INTEGER,
/** 64 bit Integer number */ /** 64 bit Integer number. */
SND_CONFIG_TYPE_INTEGER64, SND_CONFIG_TYPE_INTEGER64,
/** Real number */ /** Real number. */
SND_CONFIG_TYPE_REAL, SND_CONFIG_TYPE_REAL,
/** Character string */ /** Character string. */
SND_CONFIG_TYPE_STRING, SND_CONFIG_TYPE_STRING,
/** Pointer - runtime only - cannot be saved */ /** Pointer (runtime only, cannot be saved). */
SND_CONFIG_TYPE_POINTER, SND_CONFIG_TYPE_POINTER,
/** Compound */ /** Compound node. */
SND_CONFIG_TYPE_COMPOUND = 1024 SND_CONFIG_TYPE_COMPOUND = 1024
} snd_config_type_t; } 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; 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; 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; typedef struct _snd_config_update snd_config_update_t;
extern snd_config_t *snd_config; extern snd_config_t *snd_config;
@ -136,12 +152,13 @@ snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t itera
snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node); snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node);
snd_config_t *snd_config_iterator_entry(const snd_config_iterator_t iterator); 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 * \brief Helper macro to iterate over the children of a compound node.
* \param next Next node iterator * \param pos Iterator variable for the current node.
* \param node Compound config 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) \ #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)) 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))

22
include/conv.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Application interface library for the ALSA driver * Application interface library for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -30,25 +30,25 @@
/** /**
* \defgroup BConv Binary Value Conversion * \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) #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) #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) #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) #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) #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) #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) #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) #define snd_BE_to_host_32(val) __be32_to_cpu(val)
/** \} */ /** \} */

41
include/error.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Application interface library for the ALSA driver * Application interface library for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -34,34 +34,37 @@ extern "C" {
/** /**
* \defgroup Error Error handling * \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_BEGIN 500000 /**< Lower boundary of sound error codes. */
#define SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0) /**< protocol is not compatible */ #define SND_ERROR_INCOMPATIBLE_VERSION (SND_ERROR_BEGIN+0) /**< Kernel/library protocols are not compatible. */
const char *snd_strerror(int errnum); const char *snd_strerror(int errnum);
/** /**
* \brief Error handler * \brief Error handler callback.
* \param file File name * \param file Source file name.
* \param line Line number * \param line Line number.
* \param function Function name * \param function Function name.
* \param err errno value (or 0 if not relevant) * \param err Value of \c errno, or 0 if not relevant.
* \param fmt printf(3) format * \param fmt \c printf(3) format.
* \param ... printf(3) arguments * \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))) */; 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 snd_lib_error_handler_t snd_lib_error;
extern int snd_lib_error_set_handler(snd_lib_error_handler_t *handler); extern int snd_lib_error_set_handler(snd_lib_error_handler_t handler);
#if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 95) #if __GNUC__ > 2 || (__GNUC__ == 2 && __GNUC_MINOR__ > 95)
#define SNDERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, __VA_ARGS__) /**< show sound 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__) /**< show system error */ #define SYSERR(...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, __VA_ARGS__) /**< Shows a system error message (related to \c errno). */
#else #else
#define SNDERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, 0, ##args) /**< show sound 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) /**< show system error */ #define SYSERR(args...) snd_lib_error(__FILE__, __LINE__, __FUNCTION__, errno, ##args) /**< Shows a system error message (related to \c errno). */
#endif #endif
/** \} */ /** \} */

32
include/global.h
View file

@ -35,6 +35,9 @@ extern "C" {
/** /**
* \defgroup Global Global defines and functions * \defgroup Global Global defines and functions
* Global defines and functions. * Global defines and functions.
* \par
* The ALSA library implementation uses these macros and functions.
* Most applications probably do not need them.
* \{ * \{
*/ */
@ -45,9 +48,12 @@ extern "C" {
#ifdef PIC /* dynamic build */ #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 #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); #define SND_DLSYM_BUILD_VERSION(name, version) char __SND_DLSYM_VERSION(name, version);
#else /* static build */ #else /* static build */
@ -60,9 +66,12 @@ struct snd_dlsym_link {
extern struct snd_dlsym_link *snd_dlsym_start; 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 #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) \ #define SND_DLSYM_BUILD_VERSION(name, version) \
static struct snd_dlsym_link __SND_DLSYM_VERSION(snd_dlsym_, 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)); \ void __SND_DLSYM_VERSION(snd_dlsym_constructor_, name, version) (void) __attribute__ ((constructor)); \
@ -75,7 +84,7 @@ extern struct snd_dlsym_link *snd_dlsym_start;
#endif #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) #define SND_DLSYM_VERSION(version) __STRING(version)
void *snd_dlopen(const char *file, int mode); void *snd_dlopen(const char *file, int mode);
@ -83,10 +92,19 @@ void *snd_dlsym(void *handle, const char *name, const char *version);
int snd_dlclose(void *handle); 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; 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); typedef void (*snd_async_callback_t)(snd_async_handler_t *handler);
int snd_async_add_handler(snd_async_handler_t **handler, int fd, int snd_async_add_handler(snd_async_handler_t **handler, int fd,

32
include/input.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Application interface library for the ALSA driver * Application interface library for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -34,18 +34,30 @@ extern "C" {
/** /**
* \defgroup Input Input Interface * \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; typedef struct _snd_input snd_input_t;
/** Input type */ /** Input type. */
typedef enum _snd_input_type { typedef enum _snd_input_type {
/** Input from a stdio stream */ /** Input from a stdio stream. */
SND_INPUT_STDIO, SND_INPUT_STDIO,
/** Input from a memory buffer */ /** Input from a memory buffer. */
SND_INPUT_BUFFER SND_INPUT_BUFFER
} snd_input_type_t; } snd_input_type_t;
@ -53,7 +65,11 @@ int snd_input_stdio_open(snd_input_t **inputp, const char *file, const char *mod
int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close); int snd_input_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_buffer_open(snd_input_t **inputp, const char *buffer, ssize_t size);
int snd_input_close(snd_input_t *input); 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); char *snd_input_gets(snd_input_t *input, char *str, size_t size);
int snd_input_getc(snd_input_t *input); int snd_input_getc(snd_input_t *input);
int snd_input_ungetc(snd_input_t *input, int c); int snd_input_ungetc(snd_input_t *input, int c);

32
include/output.h
View file

@ -7,8 +7,8 @@
* \date 1998-2001 * \date 1998-2001
* *
* Application interface library for the ALSA driver * Application interface library for the ALSA driver
* */
* /*
* This library is free software; you can redistribute it and/or modify * This library is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as * it under the terms of the GNU Lesser General Public License as
* published by the Free Software Foundation; either version 2.1 of * published by the Free Software Foundation; either version 2.1 of
@ -34,18 +34,30 @@ extern "C" {
/** /**
* \defgroup Output Output Interface * \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; typedef struct _snd_output snd_output_t;
/** Output type */ /** Output type. */
typedef enum _snd_output_type { typedef enum _snd_output_type {
/** Output to a stdio stream */ /** Output to a stdio stream. */
SND_OUTPUT_STDIO, SND_OUTPUT_STDIO,
/** Output to a memory buffer */ /** Output to a memory buffer. */
SND_OUTPUT_BUFFER SND_OUTPUT_BUFFER
} snd_output_type_t; } snd_output_type_t;
@ -54,7 +66,11 @@ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close);
int snd_output_buffer_open(snd_output_t **outputp); int snd_output_buffer_open(snd_output_t **outputp);
size_t snd_output_buffer_string(snd_output_t *output, char **buf); size_t snd_output_buffer_string(snd_output_t *output, char **buf);
int snd_output_close(snd_output_t *output); 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_puts(snd_output_t *output, const char *str);
int snd_output_putc(snd_output_t *output, int c); int snd_output_putc(snd_output_t *output, int c);
int snd_output_flush(snd_output_t *output); int snd_output_flush(snd_output_t *output);

64
src/async.c
View file

@ -63,17 +63,33 @@ static void snd_async_handler(int signo ATTRIBUTE_UNUSED, siginfo_t *siginfo, vo
} }
/** /**
* \brief Add async handler * \brief Registers an async handler.
* \param handler Result - async handler * \param handler The function puts the pointer to the new async handler
* \param fd - File descriptor * object at the address specified by \p handler.
* \param callback - Async callback * \param fd The file descriptor to be associated with the callback.
* \param private_data - Private data for async callback * \param callback The async callback function.
* \result zero if success, otherwise a negative error code * \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 * This function associates the callback function with the given file,
* for the standard SIGIO signal contains the multiplexer * and saves this association in a \c snd_async_handler_t object.
* for multiple asynchronous notifiers using one sigaction *
* callback. * 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, int snd_async_add_handler(snd_async_handler_t **handler, int fd,
snd_async_callback_t callback, void *private_data) snd_async_callback_t callback, void *private_data)
@ -108,9 +124,9 @@ int snd_async_add_handler(snd_async_handler_t **handler, int fd,
} }
/** /**
* \brief Delete async handler * \brief Deletes an async handler.
* \param handler Async handler to delete * \param handler Handle of the async handler to delete.
* \result zero if success, otherwise a negative error code * \result Zero if successful, otherwise a negative error code.
*/ */
int snd_async_del_handler(snd_async_handler_t *handler) int snd_async_del_handler(snd_async_handler_t *handler)
{ {
@ -150,9 +166,13 @@ int snd_async_del_handler(snd_async_handler_t *handler)
} }
/** /**
* \brief Get signal number assigned to async handler * \brief Returns the signal number assigned to an async handler.
* \param handler Async handler * \param handler Handle to an async handler.
* \result signal number if success, otherwise a negative error code * \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) int snd_async_handler_get_signo(snd_async_handler_t *handler)
{ {
@ -161,9 +181,9 @@ int snd_async_handler_get_signo(snd_async_handler_t *handler)
} }
/** /**
* \brief Get file descriptor assigned to async handler * \brief Returns the file descriptor assigned to an async handler.
* \param handler Async handler * \param handler Handle to an async handler.
* \result file descriptor if success, otherwise a negative error code * \result The file descriptor if successful, otherwise a negative error code.
*/ */
int snd_async_handler_get_fd(snd_async_handler_t *handler) int snd_async_handler_get_fd(snd_async_handler_t *handler)
{ {
@ -172,9 +192,9 @@ int snd_async_handler_get_fd(snd_async_handler_t *handler)
} }
/** /**
* \brief Get private data assigned to async handler * \brief Returns the private data assigned to an async handler.
* \param handler Async handler * \param handler Handle to an async handler.
* \result private data if success, otherwise a negative error code * \result The \c private_data value registered with the async handler.
*/ */
void *snd_async_handler_get_callback_private(snd_async_handler_t *handler) void *snd_async_handler_get_callback_private(snd_async_handler_t *handler)
{ {

845
src/conf.c
View file

File diff suppressed because it is too large Load diff

219
src/confmisc.c
View file

@ -37,30 +37,30 @@
\section conffunc_ref Function reference \section conffunc_ref Function reference
<UL> <UL>
<LI>The getenv function - snd_func_getenv() - allows to obtain <LI>The getenv function - snd_func_getenv() - obtains
an environment value. The result is string. an environment value. The result is a string.
<LI>The igetenv function - snd_func_igetenv() - allows to obtain <LI>The igetenv function - snd_func_igetenv() - obtains
an environment value. The result is integer. an environment value. The result is an integer.
<LI>The concat function - snd_func_concat() - merges all specified <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 <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 <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 <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 <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 <LI>The pcm_id function - snd_func_pcm_id() - returns
the pcm identification. The result is string. a pcm identification. The result is a string.
<LI>The private_string - snd_func_private_string() - returns <LI>The private_string function - snd_func_private_string() - returns the
string using private_data node. string from the private_data node.
<LI>The private_card_driver - snd_func_private_card_driver() - <LI>The private_card_driver function - snd_func_private_card_driver() -
returns the driver identification using private_data node. returns the driver identification from the private_data node.
The result is string. The result is a string.
<LI>The private_pcm_subdevice - snd_func_private_pcm_subdevice() - <LI>The private_pcm_subdevice function - snd_func_private_pcm_subdevice() -
returns the PCM subdevice number using the private_data node. returns the PCM subdevice number from the private_data node.
The result is string. The result is a string.
</UL> </UL>
*/ */
@ -73,9 +73,9 @@
#include "local.h" #include "local.h"
/** /**
* \brief Get the boolean value from given ASCII string * \brief Gets the boolean value from the given ASCII string.
* \param ascii The ASCII string to be parsed * \param ascii The string to be parsed.
* \return a positive value when success otherwise a negative error number * \return 0 or 1 if successful, otherwise a negative error code.
*/ */
int snd_config_get_bool_ascii(const char *ascii) int snd_config_get_bool_ascii(const char *ascii)
{ {
@ -101,9 +101,9 @@ int snd_config_get_bool_ascii(const char *ascii)
} }
/** /**
* \brief Get the boolean value * \brief Gets the boolean value from a configuration node.
* \param conf The configuration node to be parsed * \param conf Handle to the configuration node to be parsed.
* \return a positive value when success otherwise a negative error number * \return 0 or 1 if successful, otherwise a negative error code.
*/ */
int snd_config_get_bool(const snd_config_t *conf) int snd_config_get_bool(const snd_config_t *conf)
{ {
@ -135,9 +135,9 @@ int snd_config_get_bool(const snd_config_t *conf)
} }
/** /**
* \brief Get the control interface index from given ASCII string * \brief Gets the control interface index from the given ASCII string.
* \param ascii The ASCII string to be parsed * \param ascii The string to be parsed.
* \return a positive value when success otherwise a negative error number * \return The control interface index if successful, otherwise a negative error code.
*/ */
int snd_config_get_ctl_iface_ascii(const char *ascii) int snd_config_get_ctl_iface_ascii(const char *ascii)
{ {
@ -158,9 +158,9 @@ int snd_config_get_ctl_iface_ascii(const char *ascii)
} }
/** /**
* \brief Get the control interface index * \brief Gets the control interface index from a configuration node.
* \param conf The configuration node to be parsed * \param conf Handle to the configuration node to be parsed.
* \return a positive value when success otherwise a negative error number * \return The control interface index if successful, otherwise a negative error code.
*/ */
int snd_config_get_ctl_iface(const snd_config_t *conf) int snd_config_get_ctl_iface(const snd_config_t *conf)
{ {
@ -196,12 +196,14 @@ int snd_config_get_ctl_iface(const snd_config_t *conf)
*/ */
/** /**
* \brief Get environment value * \brief Returns an environment value.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node, with vars and default definition * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with definitions for \c vars and
* \return a positive value when success otherwise a negative error number * \c default.
* \param private_data Handle to the \c private_data node.
* \return Zero if successful, otherwise a negative error code.
* *
* Example: * Example:
\code \code
@ -297,17 +299,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_getenv, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif #endif
/** /**
* \brief Get integer environment value * \brief Returns an integer environment value.
* \param dst The destination node (result type is integer) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type integer) at the address specified by \p dst.
* \param src The source node, with vars and default definition * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with definitions for \c vars and
* \return a positive value when success otherwise a negative error number * \c default.
* \param private_data Handle to the \c private_data node.
* \return Zero if successful, otherwise a negative error code.
* *
* Example: * Example:
\code \code
{ {
@func getenv @func igetenv
vars [ MY_DEVICE DEVICE D ] vars [ MY_DEVICE DEVICE D ]
default 0 default 0
} }
@ -348,19 +352,19 @@ SND_DLSYM_BUILD_VERSION(snd_func_igetenv, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif #endif
/** /**
* \brief Merge given strings * \brief Merges the given strings.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node, with strings definition * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with a definition for \c strings.
* \return a positive value when success otherwise a negative error number * \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 \code
{ {
@func concat @func concat
strings [ "a1" "b2" "c3" ] strings [ "a1" "b2" "c3" ]
default 0
} }
\endcode \endcode
*/ */
@ -436,14 +440,15 @@ SND_DLSYM_BUILD_VERSION(snd_func_concat, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif #endif
/** /**
* \brief Get data directory * \brief Returns the ALSA data directory.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node (unused) * \param src Handle to the source node.
* \return a positive value when success otherwise a negative error number * \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 \code
{ {
@func datadir @func datadir
@ -488,12 +493,14 @@ static int string_from_integer(char **dst, long v)
#endif #endif
/** /**
* \brief Get string from private_data * \brief Returns the string from \c private_data.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node (type string, id == "string") * \param src Handle to the source node.
* \return a positive value when success otherwise a negative error number * \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: * Example:
\code \code
@ -564,12 +571,14 @@ int snd_determine_driver(int card, char **driver)
#endif #endif
/** /**
* \brief Get driver identification using private_data * \brief Returns the driver identification from \c private_data.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node (type = integer, id = "card") * \param src Handle to the source node.
* \return a positive value when success otherwise a negative error number * \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: * Example:
\code \code
@ -609,12 +618,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_card_driver, SND_CONFIG_DLSYM_VERSION_E
#endif #endif
/** /**
* \brief Get driver identification * \brief Returns the driver identification for a card.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with a \c card definition.
* \return a positive value when success otherwise a negative error number * \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
* *
* Example: * Example:
\code \code
@ -666,12 +676,13 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_driver, SND_CONFIG_DLSYM_VERSION_EVALUATE)
#endif #endif
/** /**
* \brief Get card identification * \brief Returns the identification of a card.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with a \c card definition.
* \return a positive value when success otherwise a negative error number * \param private_data Handle to the \c private_data node.
* \return A non-negative value if successful, otherwise a negative error code.
* *
* Example: * Example:
\code \code
@ -737,12 +748,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_card_id, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif #endif
/** /**
* \brief Get pcm identification * \brief Returns the pcm identification of a device.
* \param dst The destination node (result type is string) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type string) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node * \param src Handle to the source node, with definitions for \c card,
* \return a positive value when success otherwise a negative error number * \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: * Example:
\code \code
@ -831,12 +844,14 @@ SND_DLSYM_BUILD_VERSION(snd_func_pcm_id, SND_CONFIG_DLSYM_VERSION_EVALUATE);
#endif #endif
/** /**
* \brief Get pcm subdevice using private_data * \brief Returns the PCM subdevice from \c private_data.
* \param dst The destination node (result type is integer) * \param dst The function puts the handle to the result configuration node
* \param root The root source node * (with type integer) at the address specified by \p dst.
* \param src The source node * \param root Handle to the root source node.
* \param private_data The private_data node (type = pointer, id = "pcm_handle") * \param src Handle to the source node.
* \return a positive value when success otherwise a negative error number * \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: * Example:
\code \code
@ -881,12 +896,16 @@ SND_DLSYM_BUILD_VERSION(snd_func_private_pcm_subdevice, SND_CONFIG_DLSYM_VERSION
#endif #endif
/** /**
* \brief Copy the referred configuration node * \brief Copies the specified configuration node.
* \param dst The destination node (result type is same as referred node) * \param dst The function puts the handle to the result configuration node
* \param root The root source node (can be modified!!!) * (with the same type as the specified node) at the address
* \param src The source node * specified by \p dst.
* \param private_data The private_data node * \param root Handle to the root source node.
* \return a positive value when success otherwise a negative error number * \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: * Example:
\code \code

50
src/dlmisc.c
View file

@ -37,13 +37,13 @@ struct snd_dlsym_link *snd_dlsym_start = NULL;
#endif #endif
/** /**
* \brief Open the dynamic library, with ALSA extension * \brief Opens a dynamic library - ALSA wrapper for \c dlopen.
* \param name name, similar to dlopen * \param name name of the library, similar to \c dlopen.
* \param mode mode, similar to dlopen * \param mode mode flags, similar to \c dlopen.
* \return pointer to handle * \return Library handle if successful, otherwise \c NULL.
* *
* 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. * the alsa-lib library. In that case, \p name is set to \c NULL.
*/ */
void *snd_dlopen(const char *name, int mode) void *snd_dlopen(const char *name, int mode)
{ {
@ -55,11 +55,11 @@ void *snd_dlopen(const char *name, int mode)
} }
/** /**
* \brief Close the dynamic library, with ALSA extension * \brief Closes a dynamic library - ALSA wrapper for \c dlclose.
* \param handle handle, similar to dlclose * \param handle Library handle, similar to \c dlclose.
* \return zero if success, otherwise an error code * \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. * the alsa-lib library.
*/ */
int snd_dlclose(void *handle) int snd_dlclose(void *handle)
@ -72,11 +72,14 @@ int snd_dlclose(void *handle)
} }
/** /**
* \brief Verify dynamically loaded symbol * \brief Verifies a dynamically loaded symbol.
* \param handle dlopen handle * \param handle Library handle, similar to \c dlsym.
* \param name name of symbol * \param name Symbol name.
* \param version version of symbol * \param version Version of the symbol.
* \return zero is success, otherwise a negative error code * \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) static int snd_dlsym_verify(void *handle, const char *name, const char *version)
{ {
@ -99,14 +102,17 @@ static int snd_dlsym_verify(void *handle, const char *name, const char *version)
} }
/** /**
* \brief Resolve the symbol, with ALSA extension * \brief Resolves a symbol from a dynamic library - ALSA wrapper for \c dlsym.
* \param handle handle, similar to dlsym * \param handle Library handle, similar to \c dlsym.
* \param name symbol name * \param name Symbol name.
* \param version symbol version * \param version Version of the symbol.
* *
* This special version of dlsym function checks also * This function can emulate dynamic linking for the static build of
* the version of symbol. The version of a symbol should * the alsa-lib library.
* 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) void *snd_dlsym(void *handle, const char *name, const char *version)
{ {

23
src/error.c
View file

@ -43,10 +43,10 @@ static const char *snd_error_codes[] =
}; };
/** /**
* \brief Get the error string. * \brief Returns the message for an error code.
* \param errnum The error code number. * \param errnum The error code number, which must be a system error code
* * or an ALSA error code.
* Returns the ASCII description of the given numeric error code. * \return The ASCII description of the given numeric error code.
*/ */
const char *snd_strerror(int errnum) const char *snd_strerror(int errnum)
{ {
@ -65,11 +65,11 @@ const char *snd_strerror(int errnum)
* \param file The filename where the error was hit. * \param file The filename where the error was hit.
* \param line The line number. * \param line The line number.
* \param function The function name. * \param function The function name.
* \param err The error number. * \param err The error code.
* \param fmt The message (including the format characters). * \param fmt The message (including the format characters).
* \param ... Optional arguments. * \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, ...) static void snd_lib_error_default(const char *file, int line, const char *function, int err, const char *fmt, ...)
{ {
@ -86,17 +86,18 @@ static void snd_lib_error_default(const char *file, int line, const char *functi
/** /**
* \ingroup Error * \ingroup Error
* Pointer to the error handler function. * 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. * \param handler The pointer to the new error handler function.
* *
* This function sets a new error handler or the default one (if the NULL * This function sets a new error handler, or (if \c handler is \c NULL)
* parameter is given) which prints the error messages to stderr. * 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; snd_lib_error = handler == NULL ? snd_lib_error_default : handler;
return 0; return 0;

83
src/input.c
View file

@ -51,9 +51,9 @@ struct _snd_input {
#endif #endif
/** /**
* \brief close input handle * \brief Closes an input handle.
* \param input Input handle * \param input The input handle to be closed.
* \return 0 on success otherwise a negative error code * \return Zero if successful, otherwise a negative error code.
*/ */
int snd_input_close(snd_input_t *input) int snd_input_close(snd_input_t *input)
{ {
@ -63,11 +63,13 @@ int snd_input_close(snd_input_t *input)
} }
/** /**
* \brief fscanf(3) like on an input handle * \brief Reads formatted input (like \c fscanf(3)) from an input handle.
* \param input Input handle * \param input The input handle.
* \param format fscanf format * \param format Format string in \c fscanf format.
* \param ... other fscanf arguments * \param ... Other \c fscanf arguments.
* \return number of input items assigned otherwise a negative error code * \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, ...) int snd_input_scanf(snd_input_t *input, const char *format, ...)
{ {
@ -80,11 +82,14 @@ int snd_input_scanf(snd_input_t *input, const char *format, ...)
} }
/** /**
* \brief fgets(3) like on an input handle * \brief Reads a line from an input handle (like \c fgets(3)).
* \param input Input handle * \param input The input handle.
* \param str Destination buffer pointer * \param str Address of the destination buffer.
* \param size Buffer size * \param size The size of the destination buffer.
* \return Pointer to buffer or NULL on error * \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) char *snd_input_gets(snd_input_t *input, char *str, size_t size)
{ {
@ -92,9 +97,9 @@ char *snd_input_gets(snd_input_t *input, char *str, size_t size)
} }
/** /**
* \brief fgetc(3) like on an input handle * \brief Reads a character from an input handle (like \c fgetc(3)).
* \param input Input handle * \param input The input handle.
* \return character read or EOF on end of file or error * \return The character read, or \c EOF on end of file or error.
*/ */
int snd_input_getc(snd_input_t *input) int snd_input_getc(snd_input_t *input)
{ {
@ -102,10 +107,10 @@ int snd_input_getc(snd_input_t *input)
} }
/** /**
* \brief ungetc(3) like on an input handle * \brief Puts the last character read back to an input handle (like \c ungetc(3)).
* \param input Input handle * \param input The input handle.
* \param c Char to push back * \param c The character to push back.
* \return character pushed back or EOF on error * \return The character pushed back, or \c EOF on error.
*/ */
int snd_input_ungetc(snd_input_t *input, int c) int snd_input_ungetc(snd_input_t *input, int c)
{ {
@ -162,11 +167,14 @@ static snd_input_ops_t snd_input_stdio_ops = {
#endif #endif
/** /**
* \brief Create a new input using an existing stdio FILE pointer * \brief Creates a new input object using an existing stdio \c FILE pointer.
* \param inputp Pointer to returned input handle * \param inputp The function puts the pointer to the new input object
* \param fp FILE pointer * at the address specified by \p inputp.
* \param close Close flag (1 if FILE is fclose'd when input handle is closed) * \param fp The \c FILE pointer to read from.
* \return 0 on success otherwise a negative error code * 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) int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close)
{ {
@ -191,11 +199,12 @@ int snd_input_stdio_attach(snd_input_t **inputp, FILE *fp, int _close)
} }
/** /**
* \brief Open a new input from a file * \brief Creates a new input object reading from a file.
* \param inputp Pointer to returned input handle * \param inputp The functions puts the pointer to the new input object
* \param file File name * at the address specified by \p inputp.
* \param mode fopen(3) open mode * \param file The name of the file to read from.
* \return 0 on success otherwise a negative error code * \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) int snd_input_stdio_open(snd_input_t **inputp, const char *file, const char *mode)
{ {
@ -284,11 +293,15 @@ static snd_input_ops_t snd_input_buffer_ops = {
#endif #endif
/** /**
* \brief Open a new input from a memory buffer * \brief Creates a new input object from a memory buffer.
* \param inputp Pointer to returned input handle * \param inputp The function puts the pointer to the new input object
* \param buf Buffer pointer * at the address specified by \p inputp.
* \param size Buffer size * \param buf Address of the input buffer.
* \return 0 on success otherwise a negative error code * \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) int snd_input_buffer_open(snd_input_t **inputp, const char *buf, ssize_t size)
{ {

85
src/output.c
View file

@ -50,9 +50,9 @@ struct _snd_output {
#endif #endif
/** /**
* \brief close output handle * \brief Closes an output handle.
* \param output Output handle * \param output The output handle to be closed.
* \return 0 on success otherwise a negative error code * \return Zero if successful, otherwise a negative error code.
*/ */
int snd_output_close(snd_output_t *output) int snd_output_close(snd_output_t *output)
{ {
@ -62,11 +62,11 @@ int snd_output_close(snd_output_t *output)
} }
/** /**
* \brief fprintf(3) like on an output handle * \brief Writes formatted output (like \c fprintf(3)) to an output handle.
* \param output Output handle * \param output The output handle.
* \param format fprintf format * \param format Format string in \c fprintf format.
* \param ... other fprintf arguments * \param ... Other \c fprintf arguments.
* \return number of characters written otherwise a negative error code * \return The number of characters written, or a negative error code.
*/ */
int snd_output_printf(snd_output_t *output, const char *format, ...) int snd_output_printf(snd_output_t *output, const char *format, ...)
{ {
@ -79,10 +79,10 @@ int snd_output_printf(snd_output_t *output, const char *format, ...)
} }
/** /**
* \brief fputs(3) like on an output handle * \brief Writes a string to an output handle (like \c fputs(3)).
* \param output Output handle * \param output The output handle.
* \param str Buffer pointer * \param str Pointer to the string.
* \return 0 on success otherwise a negative error code * \return Zero if successful, otherwise a negative error code or \c EOF.
*/ */
int snd_output_puts(snd_output_t *output, const char *str) int snd_output_puts(snd_output_t *output, const char *str)
{ {
@ -90,10 +90,10 @@ int snd_output_puts(snd_output_t *output, const char *str)
} }
/** /**
* \brief fputs(3) like on an output handle * \brief Writes a character to an output handle (like \c putc(3)).
* \param output Output handle * \param output The output handle.
* \param str Source buffer pointer * \param c The character.
* \return 0 on success otherwise a negative error code * \return Zero if successful, otherwise a negative error code or \c EOF.
*/ */
int snd_output_putc(snd_output_t *output, int c) int snd_output_putc(snd_output_t *output, int c)
{ {
@ -101,9 +101,13 @@ int snd_output_putc(snd_output_t *output, int c)
} }
/** /**
* \brief fflush(3) like on an output handle * \brief Flushes an output handle (like fflush(3)).
* \param output Output handle * \param output The output handle.
* \return 0 on success otherwise a negative error code * \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) int snd_output_flush(snd_output_t *output)
{ {
@ -160,11 +164,14 @@ static snd_output_ops_t snd_output_stdio_ops = {
#endif #endif
/** /**
* \brief Create a new output using an existing stdio FILE pointer * \brief Creates a new output object using an existing stdio \c FILE pointer.
* \param outputp Pointer to returned output handle * \param outputp The function puts the pointer to the new output object
* \param fp FILE pointer * at the address specified by \p outputp.
* \param close Close flag (1 if FILE is fclose'd when output handle is closed) * \param fp The \c FILE pointer to write to. Characters are written
* \return 0 on success otherwise a negative error code * 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) int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close)
{ {
@ -189,11 +196,12 @@ int snd_output_stdio_attach(snd_output_t **outputp, FILE *fp, int _close)
} }
/** /**
* \brief Open a new output to a file * \brief Creates a new output object writing to a file.
* \param outputp Pointer to returned output handle * \param outputp The function puts the pointer to the new output object
* \param file File name * at the address specified by \p outputp.
* \param mode fopen(3) open mode * \param file The name of the file to open.
* \return 0 on success otherwise a negative error code * \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) int snd_output_stdio_open(snd_output_t **outputp, const char *file, const char *mode)
{ {
@ -307,10 +315,14 @@ static snd_output_ops_t snd_output_buffer_ops = {
#endif #endif
/** /**
* \brief Return buffer info for a #SND_OUTPUT_TYPE_BUFFER output handle * \brief Returns the address of the buffer of a #SND_OUTPUT_TYPE_BUFFER output handle.
* \param output Output handle * \param output The output handle.
* \param buf Pointer to returned buffer * \param buf The functions puts the current address of the buffer at the
* \return size of data in buffer * 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) size_t snd_output_buffer_string(snd_output_t *output, char **buf)
{ {
@ -320,9 +332,10 @@ size_t snd_output_buffer_string(snd_output_t *output, char **buf)
} }
/** /**
* \brief Open a new output to an auto extended memory buffer * \brief Creates a new output object with an auto-extending memory buffer.
* \param outputp Pointer to returned output handle * \param outputp The function puts the pointer to the new output object
* \return 0 on success otherwise a negative error code * 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) int snd_output_buffer_open(snd_output_t **outputp)
{ {