ALSA project - the C library reference
|
Data Structures | |
struct | snd_devname_t |
Macros | |
#define | SND_CONFIG_DLSYM_VERSION_EVALUATE _dlsym_config_evaluate_001 |
dlsym version for the config evaluate callback. | |
#define | SND_CONFIG_DLSYM_VERSION_HOOK _dlsym_config_hook_001 |
dlsym version for the config hook callback. | |
#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)) |
Helper macro to iterate over the children of a compound node. More... | |
Typedefs | |
typedef struct _snd_config | snd_config_t |
Internal structure for a configuration node object. More... | |
typedef struct _snd_config_iterator * | snd_config_iterator_t |
Type for a configuration compound iterator. More... | |
typedef struct _snd_config_update | snd_config_update_t |
Internal structure for a configuration private update object. More... | |
typedef int(* | snd_config_expand_fcn_t) (snd_config_t **dst, const char *s, void *private_data) |
Enumerations | |
enum | snd_config_type_t { SND_CONFIG_TYPE_INTEGER , SND_CONFIG_TYPE_INTEGER64 , SND_CONFIG_TYPE_REAL , SND_CONFIG_TYPE_STRING , SND_CONFIG_TYPE_POINTER , SND_CONFIG_TYPE_COMPOUND = 1024 } |
Configuration node type. More... | |
Functions | |
const char * | snd_config_topdir (void) |
int | snd_config_top (snd_config_t **config) |
Creates a top level configuration node. More... | |
int | snd_config_load (snd_config_t *config, snd_input_t *in) |
Loads a configuration tree. More... | |
int | snd_config_load_string (snd_config_t **config, const char *s, size_t size) |
Loads a configuration tree from a string. More... | |
int | snd_config_load_override (snd_config_t *config, snd_input_t *in) |
Loads a configuration tree and overrides existing configuration nodes. More... | |
int | snd_config_save (snd_config_t *config, snd_output_t *out) |
Dumps the contents of a configuration node or tree. More... | |
int | snd_config_update (void) |
Updates snd_config by rereading the global configuration files (if needed). More... | |
int | snd_config_update_r (snd_config_t **top, snd_config_update_t **update, const char *path) |
Updates a configuration tree by rereading the configuration files (if needed). More... | |
int | snd_config_update_free (snd_config_update_t *update) |
Frees a private update structure. More... | |
int | snd_config_update_free_global (void) |
Frees the global configuration tree in snd_config. More... | |
int | snd_config_update_ref (snd_config_t **top) |
Updates snd_config and takes its reference. More... | |
void | snd_config_ref (snd_config_t *top) |
Take the reference of the config tree. More... | |
void | snd_config_unref (snd_config_t *top) |
Unreference the config tree. More... | |
int | snd_config_search (snd_config_t *config, const char *key, snd_config_t **result) |
Searches for a node in a configuration tree. More... | |
int | snd_config_searchv (snd_config_t *config, snd_config_t **result,...) |
Searches for a node in a configuration tree. More... | |
int | snd_config_search_definition (snd_config_t *config, const char *base, const char *key, snd_config_t **result) |
Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments. More... | |
int | snd_config_expand_custom (snd_config_t *config, snd_config_t *root, snd_config_expand_fcn_t fcn, void *private_data, snd_config_t **result) |
Expands a configuration node, applying arguments and functions. More... | |
int | snd_config_expand (snd_config_t *config, snd_config_t *root, const char *args, snd_config_t *private_data, snd_config_t **result) |
Expands a configuration node, applying arguments and functions. More... | |
int | snd_config_evaluate (snd_config_t *config, snd_config_t *root, snd_config_t *private_data, snd_config_t **result) |
Evaluates a configuration node at runtime. More... | |
int | snd_config_evaluate_string (snd_config_t **dst, const char *s, snd_config_expand_fcn_t fcn, void *private_data) |
int | snd_config_add (snd_config_t *config, snd_config_t *child) |
Adds a child to a compound configuration node. More... | |
int | snd_config_add_before (snd_config_t *before, snd_config_t *child) |
Adds a child before another child configuration node. More... | |
int | snd_config_add_after (snd_config_t *after, snd_config_t *child) |
Adds a child after another child configuration node. More... | |
int | snd_config_remove (snd_config_t *config) |
Removes a configuration node from its tree. More... | |
int | snd_config_delete (snd_config_t *config) |
Frees a configuration node. More... | |
int | snd_config_delete_compound_members (const snd_config_t *config) |
Deletes the children of a node. More... | |
int | snd_config_copy (snd_config_t **dst, snd_config_t *src) |
Creates a copy of a configuration node. More... | |
int | snd_config_substitute (snd_config_t *dst, snd_config_t *src) |
Substitutes one configuration node to another. More... | |
int | snd_config_merge (snd_config_t *dst, snd_config_t *src, int override) |
In-place merge of two config handles. More... | |
int | snd_config_make (snd_config_t **config, const char *key, snd_config_type_t type) |
Creates a configuration node. More... | |
int | snd_config_make_integer (snd_config_t **config, const char *key) |
Creates an integer configuration node. More... | |
int | snd_config_make_integer64 (snd_config_t **config, const char *key) |
Creates a 64-bit-integer configuration node. More... | |
int | snd_config_make_real (snd_config_t **config, const char *key) |
Creates a real number configuration node. More... | |
int | snd_config_make_string (snd_config_t **config, const char *key) |
Creates a string configuration node. More... | |
int | snd_config_make_pointer (snd_config_t **config, const char *key) |
Creates a pointer configuration node. More... | |
int | snd_config_make_compound (snd_config_t **config, const char *key, int join) |
Creates an empty compound configuration node. More... | |
int | snd_config_make_path (snd_config_t **config, snd_config_t *root, const char *key, int join, int override) |
Creates an empty compound configuration node in the path. More... | |
int | snd_config_imake_integer (snd_config_t **config, const char *key, const long value) |
Creates an integer configuration node with the given initial value. More... | |
int | snd_config_imake_integer64 (snd_config_t **config, const char *key, const long long value) |
Creates a 64-bit-integer configuration node with the given initial value. More... | |
int | snd_config_imake_real (snd_config_t **config, const char *key, const double value) |
Creates a real number configuration node with the given initial value. More... | |
int | snd_config_imake_string (snd_config_t **config, const char *key, const char *ascii) |
Creates a string configuration node with the given initial value. More... | |
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) |
Creates a pointer configuration node with the given initial value. More... | |
snd_config_type_t | snd_config_get_type (const snd_config_t *config) |
Returns the type of a configuration node. More... | |
int | snd_config_is_array (const snd_config_t *config) |
Returns if the compound is an array (and count of items). More... | |
int | snd_config_is_empty (const snd_config_t *config) |
Returns if the compound has no fields (is empty). More... | |
int | snd_config_set_id (snd_config_t *config, const char *id) |
Sets the id of a configuration node. More... | |
int | snd_config_set_integer (snd_config_t *config, long value) |
Changes the value of an integer configuration node. More... | |
int | snd_config_set_integer64 (snd_config_t *config, long long value) |
Changes the value of a 64-bit-integer configuration node. More... | |
int | snd_config_set_real (snd_config_t *config, double value) |
Changes the value of a real-number configuration node. More... | |
int | snd_config_set_string (snd_config_t *config, const char *value) |
Changes the value of a string configuration node. More... | |
int | snd_config_set_ascii (snd_config_t *config, const char *ascii) |
Changes the value of a configuration node. More... | |
int | snd_config_set_pointer (snd_config_t *config, const void *ptr) |
Changes the value of a pointer configuration node. More... | |
int | snd_config_get_id (const snd_config_t *config, const char **value) |
Returns the id of a configuration node. More... | |
int | snd_config_get_integer (const snd_config_t *config, long *value) |
Returns the value of an integer configuration node. More... | |
int | snd_config_get_integer64 (const snd_config_t *config, long long *value) |
Returns the value of a 64-bit-integer configuration node. More... | |
int | snd_config_get_real (const snd_config_t *config, double *value) |
Returns the value of a real-number configuration node. More... | |
int | snd_config_get_ireal (const snd_config_t *config, double *value) |
Returns the value of a real or integer configuration node. More... | |
int | snd_config_get_string (const snd_config_t *config, const char **value) |
Returns the value of a string configuration node. More... | |
int | snd_config_get_ascii (const snd_config_t *config, char **value) |
Returns the value of a configuration node as a string. More... | |
int | snd_config_get_pointer (const snd_config_t *config, const void **value) |
Returns the value of a pointer configuration node. More... | |
int | snd_config_test_id (const snd_config_t *config, const char *id) |
Compares the id of a configuration node to a given string. More... | |
snd_config_iterator_t | snd_config_iterator_first (const snd_config_t *node) |
Returns an iterator pointing to a node's first child. More... | |
snd_config_iterator_t | snd_config_iterator_next (const snd_config_iterator_t iterator) |
Returns an iterator pointing to the next sibling. More... | |
snd_config_iterator_t | snd_config_iterator_end (const snd_config_t *node) |
Returns an iterator that ends a node's children list. More... | |
snd_config_t * | snd_config_iterator_entry (const snd_config_iterator_t iterator) |
Returns the configuration node handle pointed to by an iterator. More... | |
int | snd_config_get_bool_ascii (const char *ascii) |
Gets the boolean value from the given ASCII string. More... | |
int | snd_config_get_bool (const snd_config_t *conf) |
Gets the boolean value from a configuration node. More... | |
int | snd_config_get_card (const snd_config_t *conf) |
Gets the card number from a configuration node. More... | |
int | snd_config_get_ctl_iface_ascii (const char *ascii) |
Gets the control interface index from the given ASCII string. More... | |
int | snd_config_get_ctl_iface (const snd_config_t *conf) |
Gets the control interface index from a configuration node. More... | |
int | snd_names_list (const char *iface, snd_devname_t **list) |
This function is unimplemented. More... | |
void | snd_names_list_free (snd_devname_t *list) |
This function is unimplemented. More... | |
Variables | |
snd_config_t * | snd_config |
Configuration top-level node (the global configuration). More... | |
snd_config_t * | snd_config = NULL |
Configuration top-level node (the global configuration). More... | |
The configuration functions and types allow you to read, enumerate, modify and write the contents of ALSA configuration files.
#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)) |
Helper macro to iterate over the children of a compound node.
[in,out] | pos | Iterator variable for the current node. |
[in,out] | next | Temporary iterator variable for the next node. |
[in] | node | Handle to the compound configuration node to iterate over. |
Use this macro like a for
statement, e.g.:
This macro allows deleting or removing the current node.
typedef struct _snd_config_iterator* snd_config_iterator_t |
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 snd_config_t |
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_update snd_config_update_t |
Internal structure for a configuration private update object.
The ALSA library uses this structure to save private update information.
enum snd_config_type_t |
Configuration node type.
int snd_config_add | ( | snd_config_t * | parent, |
snd_config_t * | child | ||
) |
Adds a child to a compound configuration node.
parent | Handle to a compound configuration node. |
child | Handle to the configuration node to be added. |
This function makes the node child a child of the node parent.
The parent node then owns the child node, i.e., the child node gets deleted together with its parent.
child must have an id.
int snd_config_add_after | ( | snd_config_t * | after, |
snd_config_t * | child | ||
) |
Adds a child after another child configuration node.
after | Handle to the start configuration node. |
child | Handle to the configuration node to be added. |
This function makes the node child a child of the parent of the node after.
The parent node then owns the child node, i.e., the child node gets deleted together with its parent.
child must have an id.
int snd_config_add_before | ( | snd_config_t * | before, |
snd_config_t * | child | ||
) |
Adds a child before another child configuration node.
before | Handle to the start configuration node. |
child | Handle to the configuration node to be added. |
This function makes the node child a child of the parent of the node before.
The parent node then owns the child node, i.e., the child node gets deleted together with its parent.
child must have an id.
int snd_config_copy | ( | snd_config_t ** | dst, |
snd_config_t * | src | ||
) |
Creates a copy of a configuration node.
[out] | dst | The function puts the handle to the new configuration node at the address specified by dst. |
[in] | src | Handle to the source configuration node. |
This function creates a deep copy, i.e., if src is a compound node, all children are copied recursively.
int snd_config_delete | ( | snd_config_t * | config | ) |
Frees a configuration node.
config | Handle to the configuration node to be deleted. |
This function frees a configuration node and all its resources.
If the node is a child node, it is removed from the tree before being deleted.
If the node is a compound node, its descendants (the whole subtree) are deleted recursively.
The function is supposed to be called only for locally copied config trees. For the global tree, take the reference via snd_config_update_ref and free it via snd_config_unref.
int snd_config_delete_compound_members | ( | const snd_config_t * | config | ) |
Deletes the children of a node.
config | Handle to the compound configuration node. |
This function removes and frees all children of a configuration node.
Any compound nodes among the children of config are deleted recursively.
After a successful call to this function, config is an empty compound node.
int snd_config_evaluate | ( | snd_config_t * | config, |
snd_config_t * | root, | ||
snd_config_t * | private_data, | ||
snd_config_t ** | result | ||
) |
Evaluates a configuration node at runtime.
[in,out] | config | Handle to the source configuration node. |
[in] | root | Handle to the root of the source configuration. |
[in] | private_data | Handle to the private data node for runtime evaluation. |
result | Must be NULL . |
This function evaluates any functions (@func
) in config and replaces those nodes with the respective function results.
int snd_config_expand | ( | snd_config_t * | config, |
snd_config_t * | root, | ||
const char * | args, | ||
snd_config_t * | private_data, | ||
snd_config_t ** | result | ||
) |
Expands a configuration node, applying arguments and functions.
[in] | config | Handle to the configuration node. |
[in] | root | Handle to the root configuration node. |
[in] | args | Arguments string, can be NULL . |
[in] | private_data | Handle to the private data node for functions. |
[out] | result | The function puts the handle to the result configuration node at the address specified by result. |
If config has arguments (defined by a child with id @args
), this function replaces any string node beginning with $ with the respective argument value, or the default argument value, or nothing. Furthermore, any functions are evaluated (see snd_config_evaluate). The resulting copy of config is returned in result.
int snd_config_expand_custom | ( | snd_config_t * | config, |
snd_config_t * | root, | ||
snd_config_expand_fcn_t | fcn, | ||
void * | private_data, | ||
snd_config_t ** | result | ||
) |
Expands a configuration node, applying arguments and functions.
[in] | config | Handle to the configuration node. |
[in] | root | Handle to the root configuration node. |
[in] | fcn | Custom function to obtain the referred variable name |
[in] | private_data | Private data node for the custom function |
[out] | result | The function puts the handle to the result configuration node at the address specified by result. |
If config has arguments (defined by a child with id @args
), this function replaces any string node beginning with $ with the respective argument value, or the default argument value, or nothing. Furthermore, any functions are evaluated (see snd_config_evaluate). The resulting copy of config is returned in result.
The new tree is not evaluated (snd_config_evaluate).
int snd_config_get_ascii | ( | const snd_config_t * | config, |
char ** | ascii | ||
) |
Returns the value of a configuration node as a string.
[in] | config | Handle to the configuration node. |
[out] | ascii | The function puts the pointer to the returned string at the address specified by ascii. |
This function dynamically allocates the returned string. The application is responsible for deleting it with free()
when it is no longer used.
For a string node with NULL
value, the returned string is NULL
.
Supported node types are SND_CONFIG_TYPE_INTEGER, SND_CONFIG_TYPE_INTEGER64, SND_CONFIG_TYPE_REAL, and SND_CONFIG_TYPE_STRING.
int snd_config_get_bool | ( | const snd_config_t * | conf | ) |
Gets the boolean value from a configuration node.
conf | Handle to the configuration node to be parsed. |
int snd_config_get_bool_ascii | ( | const char * | ascii | ) |
Gets the boolean value from the given ASCII string.
ascii | The string to be parsed. |
int snd_config_get_card | ( | const snd_config_t * | conf | ) |
Gets the card number from a configuration node.
conf | Handle to the configuration node to be parsed. |
int snd_config_get_ctl_iface | ( | const snd_config_t * | conf | ) |
Gets the control interface index from a configuration node.
conf | Handle to the configuration node to be parsed. |
int snd_config_get_ctl_iface_ascii | ( | const char * | ascii | ) |
Gets the control interface index from the given ASCII string.
ascii | The string to be parsed. |
int snd_config_get_id | ( | const snd_config_t * | config, |
const char ** | id | ||
) |
Returns the id of a configuration node.
[in] | config | Handle to the configuration node. |
[out] | id | The function puts the pointer to the id string at the address specified by id. |
The returned string is owned by the configuration node; the application must not modify or delete it, and the string becomes invalid when the node's id changes or when the node is freed.
If the node does not have an id, *id is set to NULL
.
int snd_config_get_integer | ( | const snd_config_t * | config, |
long * | ptr | ||
) |
Returns the value of an integer configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The node's value. |
int snd_config_get_integer64 | ( | const snd_config_t * | config, |
long long * | ptr | ||
) |
Returns the value of a 64-bit-integer configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The node's value. |
int snd_config_get_ireal | ( | const snd_config_t * | config, |
double * | ptr | ||
) |
Returns the value of a real or integer configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The node's value. |
If the node's type is integer or integer64, the value is converted to the double
type on the fly.
int snd_config_get_pointer | ( | const snd_config_t * | config, |
const void ** | ptr | ||
) |
Returns the value of a pointer configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The function puts the node's value at the address specified by ptr. |
int snd_config_get_real | ( | const snd_config_t * | config, |
double * | ptr | ||
) |
Returns the value of a real-number configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The node's value. |
int snd_config_get_string | ( | const snd_config_t * | config, |
const char ** | ptr | ||
) |
Returns the value of a string configuration node.
[in] | config | Handle to the configuration node. |
[out] | ptr | The function puts the node's value at the address specified by ptr. |
The returned string is owned by the configuration node; the application must not modify or delete it, and the string becomes invalid when the node's value changes or when the node is freed.
The string may be NULL
.
snd_config_type_t snd_config_get_type | ( | const snd_config_t * | config | ) |
Returns the type of a configuration node.
config | Handle to the configuration node. |
int snd_config_imake_integer | ( | snd_config_t ** | config, |
const char * | id, | ||
const long | value | ||
) |
Creates an integer configuration node with the given initial value.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | value | The initial value of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_INTEGER and with value value.
int snd_config_imake_integer64 | ( | snd_config_t ** | config, |
const char * | id, | ||
const long long | value | ||
) |
Creates a 64-bit-integer configuration node with the given initial value.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | value | The initial value of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_INTEGER64 and with value value.
int snd_config_imake_pointer | ( | snd_config_t ** | config, |
const char * | id, | ||
const void * | value | ||
) |
Creates a pointer configuration node with the given initial value.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | value | The initial value of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_POINTER and with value value
.
int snd_config_imake_real | ( | snd_config_t ** | config, |
const char * | id, | ||
const double | value | ||
) |
Creates a real number configuration node with the given initial value.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | value | The initial value of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_REAL and with value value.
int snd_config_imake_string | ( | snd_config_t ** | config, |
const char * | id, | ||
const char * | value | ||
) |
Creates a string configuration node with the given initial value.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | value | The initial value of the new node. May be NULL . |
This function creates a new node of type SND_CONFIG_TYPE_STRING and with a copy of the string value
.
int snd_config_is_array | ( | const snd_config_t * | config | ) |
Returns if the compound is an array (and count of items).
config | Handle to the configuration node. |
int snd_config_is_empty | ( | const snd_config_t * | config | ) |
Returns if the compound has no fields (is empty).
config | Handle to the configuration node. |
snd_config_iterator_t snd_config_iterator_end | ( | const snd_config_t * | config | ) |
Returns an iterator that ends a node's children list.
[in] | config | Handle to a configuration node. |
config must be a compound node.
The return value can be understood as pointing past the last child of config.
snd_config_t * snd_config_iterator_entry | ( | const snd_config_iterator_t | iterator | ) |
Returns the configuration node handle pointed to by an iterator.
[in] | iterator | A configuration node iterator. |
snd_config_iterator_t snd_config_iterator_first | ( | const snd_config_t * | config | ) |
Returns an iterator pointing to a node's first child.
[in] | config | Handle to a configuration node. |
config must be a compound node.
The returned iterator is valid if it is not equal to the return value of snd_config_iterator_end on config.
Use snd_config_iterator_entry to get the handle of the node pointed to.
snd_config_iterator_t snd_config_iterator_next | ( | const snd_config_iterator_t | iterator | ) |
Returns an iterator pointing to the next sibling.
[in] | iterator | An iterator pointing to a child configuration node. |
The returned iterator is valid if it is not equal to the return value of snd_config_iterator_end on the node's parent.
Use snd_config_iterator_entry to get the handle of the node pointed to.
int snd_config_load | ( | snd_config_t * | config, |
snd_input_t * | in | ||
) |
Loads a configuration tree.
config | Handle to a top level configuration node. |
in | Input handle to read the configuration from. |
The definitions loaded from the input are added to config, which must be a compound node.
int snd_config_load_override | ( | snd_config_t * | config, |
snd_input_t * | in | ||
) |
Loads a configuration tree and overrides existing configuration nodes.
config | Handle to a top level configuration node. |
in | Input handle to read the configuration from. |
This function loads definitions from in into config like snd_config_load, but the default mode for input nodes is 'override' (!) instead of 'merge+create' (+).
int snd_config_load_string | ( | snd_config_t ** | config, |
const char * | s, | ||
size_t | size | ||
) |
Loads a configuration tree from a string.
[out] | The | function puts the handle to the configuration node loaded from the file(s) at the address specified by config. |
[in] | s | String with the ASCII configuration |
[in] | size | String size, if zero, a C string is expected (with termination) |
The definitions loaded from the string are put to config, which is created as a new top node.
int snd_config_make | ( | snd_config_t ** | config, |
const char * | id, | ||
snd_config_type_t | type | ||
) |
Creates a configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | type | The type of the new node. |
This functions creates a new node of the specified type. The new node has id id, which may be NULL
.
The value of the new node is zero (for numbers), or NULL
(for strings and pointers), or empty (for compound nodes).
int snd_config_make_compound | ( | snd_config_t ** | config, |
const char * | id, | ||
int | join | ||
) |
Creates an empty compound configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
[in] | join | Join flag. |
This function creates a new empty node of type SND_CONFIG_TYPE_COMPOUND.
join determines how the compound node's id is printed when the configuration is saved to a text file. For example, if the join flag of compound node a
is zero, the output will look as follows:
If, however, the join flag of a
is nonzero, its id will be joined with its children's ids, like this:
An empty compound node with its join flag set would result in no output, i.e., after saving and reloading the configuration file, that compound node would be lost.
int snd_config_make_integer | ( | snd_config_t ** | config, |
const char * | id | ||
) |
Creates an integer configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_INTEGER and with value 0
.
int snd_config_make_integer64 | ( | snd_config_t ** | config, |
const char * | id | ||
) |
Creates a 64-bit-integer configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_INTEGER64 and with value 0
.
int snd_config_make_path | ( | snd_config_t ** | config, |
snd_config_t * | root, | ||
const char * | key, | ||
int | join, | ||
int | override | ||
) |
Creates an empty compound configuration node in the path.
[out] | config | The function puts the handle to the new or existing compound node at the address specified by config. |
[in] | root | The id of the new node. |
[in] | key | The id of the new node. |
[in] | join | Join flag. |
[in] | override | Override flag. |
This function creates a new empty node of type SND_CONFIG_TYPE_COMPOUND if the path does not exist. Otherwise, the node from the current configuration tree is returned without any modification. The join argument is ignored in this case.
join determines how the compound node's id is printed when the configuration is saved to a text file. For example, if the join flag of compound node a
is zero, the output will look as follows:
If, however, the join flag of a
is nonzero, its id will be joined with its children's ids, like this:
An empty compound node with its join flag set would result in no output, i.e., after saving and reloading the configuration file, that compound node would be lost.
int snd_config_make_pointer | ( | snd_config_t ** | config, |
const char * | id | ||
) |
Creates a pointer configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_POINTER and with value NULL
.
int snd_config_make_real | ( | snd_config_t ** | config, |
const char * | id | ||
) |
Creates a real number configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_REAL and with value 0.0
.
int snd_config_make_string | ( | snd_config_t ** | config, |
const char * | id | ||
) |
Creates a string configuration node.
[out] | config | The function puts the handle to the new node at the address specified by config. |
[in] | id | The id of the new node. |
This function creates a new node of type SND_CONFIG_TYPE_STRING and with value NULL
.
int snd_config_merge | ( | snd_config_t * | dst, |
snd_config_t * | src, | ||
int | override | ||
) |
In-place merge of two config handles.
dst[out] | Config handle for the merged contents |
src[in] | Config handle to merge into dst (may be NULL) |
override[in] | Override flag |
This function merges all fields from the source compound to the destination compound. When the override flag is set, the related subtree in dst is replaced from src.
When override is not set, the child compounds are traversed and merged.
The configuration elements other than compounds are always substituted (overwritten) from the src config handle.
The src handle is deleted.
Note: On error, config handles may be modified.
void snd_config_ref | ( | snd_config_t * | cfg | ) |
Take the reference of the config tree.
Increases a reference counter of the given config tree.
This function is supposed to be thread-safe.
int snd_config_remove | ( | snd_config_t * | config | ) |
Removes a configuration node from its tree.
config | Handle to the configuration node to be removed. |
This function makes config a top-level node, i.e., if config has a parent, then config is removed from the list of the parent's children.
This functions does not free the removed node.
int snd_config_save | ( | snd_config_t * | config, |
snd_output_t * | out | ||
) |
Dumps the contents of a configuration node or tree.
config | Handle to the (root) configuration node. |
out | Output handle. |
This function writes a textual representation of config's value to the output out.
int snd_config_search | ( | snd_config_t * | config, |
const char * | key, | ||
snd_config_t ** | result | ||
) |
Searches for a node in a configuration tree.
[in] | config | Handle to the root of the configuration (sub)tree to search. |
[in] | key | Search key: one or more node ids, separated with dots. |
[out] | result | When result != NULL , the function puts the handle to the node found at the address specified by result. |
This function searches for a child node of config that is identified by key, which contains either the id of a direct child node of config, or a series of ids, separated with dots, where each id specifies a node that is contained in the previous compound node.
In the following example, the comment after each node shows the search key to find that node, assuming that config is a handle to the compound node with id config:
int snd_config_search_definition | ( | snd_config_t * | config, |
const char * | base, | ||
const char * | name, | ||
snd_config_t ** | result | ||
) |
Searches for a definition in a configuration tree, using aliases and expanding hooks and arguments.
[in] | config | Handle to the configuration (sub)tree to search. |
[in] | base | Implicit key base, or NULL for none. |
[in] | name | Key suffix, optionally with arguments. |
[out] | result | The function puts the handle to the expanded found node at the address specified by result. |
This functions searches for a child node of config, allowing aliases and expanding hooks, like snd_config_search_alias_hooks.
If name contains a colon (:), the rest of the string after the colon contains arguments that are expanded as with snd_config_expand.
In any case, result is a new node that must be freed by the caller.
int snd_config_searchv | ( | snd_config_t * | config, |
snd_config_t ** | result, | ||
... | |||
) |
Searches for a node in a configuration tree.
[in] | config | Handle to the root of the configuration (sub)tree to search. |
[out] | result | When result != NULL , the function puts the handle to the node found at the address specified by result. |
[in] | ... | One or more concatenated dot-separated search keys, terminated with NULL . |
This functions searches for a child node of config like snd_config_search, but the search key is the concatenation of all passed search key strings. For example, the call
is equivalent to the call
int snd_config_set_ascii | ( | snd_config_t * | config, |
const char * | ascii | ||
) |
Changes the value of a configuration node.
config | Handle to the configuration node. |
ascii | The new value for the node, as an ASCII string. |
This function changes the node's value to a new value that is parsed from the string ascii. ascii must not be NULL
, not even for a string node.
The node's type does not change, i.e., the string must contain a valid value with the same type as the node's type. For a string node, the node's new value is a copy of ascii.
int snd_config_set_id | ( | snd_config_t * | config, |
const char * | id | ||
) |
Sets the id of a configuration node.
config | Handle to the configuration node. |
id | The new node id, must not be NULL . |
This function stores a copy of id in the node.
NULL
. int snd_config_set_integer | ( | snd_config_t * | config, |
long | value | ||
) |
Changes the value of an integer configuration node.
config | Handle to the configuration node. |
value | The new value for the node. |
int snd_config_set_integer64 | ( | snd_config_t * | config, |
long long | value | ||
) |
Changes the value of a 64-bit-integer configuration node.
config | Handle to the configuration node. |
value | The new value for the node. |
int snd_config_set_pointer | ( | snd_config_t * | config, |
const void * | value | ||
) |
Changes the value of a pointer configuration node.
config | Handle to the configuration node. |
value | The new value for the node. May be NULL . |
This function does not free the old pointer in the node.
int snd_config_set_real | ( | snd_config_t * | config, |
double | value | ||
) |
Changes the value of a real-number configuration node.
config | Handle to the configuration node. |
value | The new value for the node. |
int snd_config_set_string | ( | snd_config_t * | config, |
const char * | value | ||
) |
Changes the value of a string configuration node.
config | Handle to the configuration node. |
value | The new value for the node. May be NULL . |
This function deletes the old string in the node and stores a copy of value string in the node.
int snd_config_substitute | ( | snd_config_t * | dst, |
snd_config_t * | src | ||
) |
Substitutes one configuration node to another.
dst | Handle to the destination node. |
src | Handle to the source node. Must not be the same as dst. |
If both nodes are compounds, the source compound node members will be moved to the destination compound node. The original destination compound node members will be deleted (overwritten).
If the destination node is a compound and the source node is an ordinary type, the compound members are deleted (including their contents).
Otherwise, the source node's value replaces the destination node's value.
In any case, a successful call to this function frees the source node.
int snd_config_test_id | ( | const snd_config_t * | config, |
const char * | id | ||
) |
Compares the id of a configuration node to a given string.
config | Handle to the configuration node. |
id | ASCII id. |
strcmp
function, i.e., less than zero if config's id is lexicographically less than id, zero if config's id is equal to id, greater than zero otherwise. int snd_config_top | ( | snd_config_t ** | config | ) |
Creates a top level configuration node.
[out] | config | Handle to the new node. |
The returned node is an empty compound node without a parent and without an id.
void snd_config_unref | ( | snd_config_t * | cfg | ) |
Unreference the config tree.
Decreases a reference counter of the given config tree, and eventually deletes the tree if all references are gone. This is the counterpart of snd_config_unref.
Also, the config taken via snd_config_update_ref must be unreferenced by this function, too.
This function is supposed to be thread-safe.
int snd_config_update | ( | void | ) |
Updates snd_config by rereading the global configuration files (if needed).
int snd_config_update_free | ( | snd_config_update_t * | update | ) |
Frees a private update structure.
[in] | update | The private update structure to free. |
int snd_config_update_free_global | ( | void | ) |
Frees the global configuration tree in snd_config.
This functions releases all resources of the global configuration tree, and sets snd_config to NULL
.
int snd_config_update_r | ( | snd_config_t ** | _top, |
snd_config_update_t ** | _update, | ||
const char * | cfgs | ||
) |
Updates a configuration tree by rereading the configuration files (if needed).
[in,out] | _top | Address of the handle to the top-level node. |
[in,out] | _update | Address of a pointer to private update information. |
[in] | cfgs | A list of configuration file names, delimited with ':'. If cfgs is NULL , the default global configuration file is used. |
The variables pointed to by _top and _update can be initialized to NULL
before the first call to this function. The private update information holds information about all used configuration files that allows this function to detects changes to them; this data can be freed with snd_config_update_free.
The global configuration files are specified in the environment variable ALSA_CONFIG_PATH
.
int snd_config_update_ref | ( | snd_config_t ** | top | ) |
Updates snd_config and takes its reference.
Unlike snd_config_update, this function increases a reference counter so that the obtained tree won't be deleted until unreferenced by snd_config_unref.
This function is supposed to be thread-safe.
int snd_names_list | ( | const char * | iface, |
snd_devname_t ** | list | ||
) |
This function is unimplemented.
void snd_names_list_free | ( | snd_devname_t * | list | ) |
This function is unimplemented.
|
extern |
Configuration top-level node (the global configuration).
This variable contains a handle to the top-level configuration node, as loaded from global configuration file.
This variable is initialized or updated by snd_config_update. Functions like snd_pcm_open (that use a device name from the global configuration) automatically call snd_config_update. Before the first call to snd_config_update, this variable is NULL
.
The global configuration files are specified in the environment variable ALSA_CONFIG_PATH
. If this is not set, the default value is "/usr/share/alsa/alsa.conf".
snd_config_t* snd_config = NULL |
Configuration top-level node (the global configuration).
This variable contains a handle to the top-level configuration node, as loaded from global configuration file.
This variable is initialized or updated by snd_config_update. Functions like snd_pcm_open (that use a device name from the global configuration) automatically call snd_config_update. Before the first call to snd_config_update, this variable is NULL
.
The global configuration files are specified in the environment variable ALSA_CONFIG_PATH
. If this is not set, the default value is "/usr/share/alsa/alsa.conf".