/**
- * \file <alsa/conf.h>
+ * \file include/conf.h
* \brief Application interface library for the ALSA driver
- * \author Jaroslav Kysela <perex@suse.cz>
+ * \author Jaroslav Kysela <perex@perex.cz>
* \author Abramo Bagnara <abramo@alsa-project.org>
* \author Takashi Iwai <tiwai@suse.de>
* \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 */
+/** \brief 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;
int snd_config_update_free(snd_config_update_t *update);
int snd_config_update_free_global(void);
+int snd_config_update_ref(snd_config_t **top);
+void snd_config_ref(snd_config_t *top);
+void snd_config_unref(snd_config_t *top);
+
int snd_config_search(snd_config_t *config, const char *key,
snd_config_t **result);
int snd_config_searchv(snd_config_t *config,
int snd_config_imake_integer64(snd_config_t **config, const char *key, const long long value);
int snd_config_imake_real(snd_config_t **config, const char *key, const double value);
int snd_config_imake_string(snd_config_t **config, const char *key, const char *ascii);
+int snd_config_imake_safe_string(snd_config_t **config, const char *key, const char *ascii);
int snd_config_imake_pointer(snd_config_t **config, const char *key, const void *ptr);
snd_config_type_t snd_config_get_type(const snd_config_t *config);
int snd_config_get_pointer(const snd_config_t *config, const void **value);
int snd_config_test_id(const snd_config_t *config, const char *id);
-const snd_config_iterator_t snd_config_iterator_first(const snd_config_t *node);
-const snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t iterator);
-const snd_config_iterator_t snd_config_iterator_end(const snd_config_t *node);
+snd_config_iterator_t snd_config_iterator_first(const snd_config_t *node);
+snd_config_iterator_t snd_config_iterator_next(const snd_config_iterator_t iterator);
+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[in,out] pos Iterator variable for the current node.
+ * \param[in,out] next Temporary iterator variable for the next node.
+ * \param[in] node Handle to the compound configuration node to iterate over.
+ *
+ * Use this macro like a \c for statement, e.g.:
+ * \code
+ * snd_config_iterator_t pos, next;
+ * snd_config_for_each(pos, next, node) {
+ * snd_config_t *entry = snd_config_iterator_entry(pos);
+ * ...
+ * }
+ * \endcode
*
- * This macro is designed to permit the removal of current node.
+ * This macro allows deleting or removing 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))
int snd_config_get_ctl_iface_ascii(const char *ascii);
int snd_config_get_ctl_iface(const snd_config_t *conf);
+/* Names functions */
+
+/**
+ * Device-name list element
+ */
+typedef struct snd_devname snd_devname_t;
+
+/**
+ * Device-name list element (definition)
+ */
+struct snd_devname {
+ char *name; /**< Device name string */
+ char *comment; /**< Comments */
+ snd_devname_t *next; /**< Next pointer */
+};
+
+int snd_names_list(const char *iface, snd_devname_t **list);
+void snd_names_list_free(snd_devname_t *list);
+
/** \} */
#ifdef __cplusplus
#endif
#endif /* __ALSA_CONF_H */
-