Asterisk.org: Developer Documentation (28 Oct 2009)

Wed Oct 28 15:47:53 2009

## Asterisk developer's documentation

# config.h

Go to the documentation of this file.

    00001 /*
    00002  * Asterisk -- An open source telephony toolkit.
    00003  *
    00004  * Copyright (C) 1999 - 2005, Digium, Inc.
    00005  *
    00006  * Mark Spencer <markster@digium.com>
    00007  *
    00008  * See http://www.asterisk.org for more information about
    00009  * the Asterisk project. Please do not directly contact
    00010  * any of the maintainers of this project for assistance;
    00011  * the project provides a web site, mailing lists and IRC
    00012  * channels for your use.
    00013  *
    00014  * This program is free software, distributed under the terms of
    00015  * the GNU General Public License Version 2. See the LICENSE file
    00016  * at the top of the source tree.
    00017  */
    00018
    00019 /*! \file
    00020  * \brief Configuration File Parser
    00021  */
    00022
    00023 #ifndef _ASTERISK_CONFIG_H
    00024 #define _ASTERISK_CONFIG_H
    00025
    00026 #if defined(__cplusplus) || defined(c_plusplus)
    00027 extern "C" {
    00028 #endif
    00029
    00030 #include <stdarg.h>
    00031
    00032 struct ast_config;
    00033
    00034 struct ast_category;
    00035
    00036 struct ast_variable {
    00037    char *name;
    00038    char *value;
    00039    int lineno;
    00040    int object;    /*!< 0 for variable, 1 for object */
    00041    int blanklines;   /*!< Number of blanklines following entry */
    00042    struct ast_comment *precomments;
    00043    struct ast_comment *sameline;
    00044    struct ast_variable *next;
    00045    char stuff[0];
    00046 };
    00047
    00048 typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config);
    00049 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
    00050 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
    00051 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
    00052
    00053 struct ast_config_engine {
    00054    char *name;
    00055    config_load_func *load_func;
    00056    realtime_var_get *realtime_func;
    00057    realtime_multi_get *realtime_multi_func;
    00058    realtime_update *update_func;
    00059    struct ast_config_engine *next;
    00060 };
    00061
    00062 /*! \brief Load a config file
    00063  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
    00064  * Create a config structure from a given configuration file.
    00065  *
    00066  * Returns NULL on error, or an ast_config data structure on success
    00067  */
    00068 struct ast_config *ast_config_load(const char *filename);
    00069
    00070 /*! \brief Destroys a config
    00071  * \param config pointer to config data structure
    00072  * Free memory associated with a given config
    00073  *
    00074  */
    00075 void ast_config_destroy(struct ast_config *config);
    00076
    00077 /*! \brief Goes through categories
    00078  * \param config Which config structure you wish to "browse"
    00079  * \param prev A pointer to a previous category.
    00080  * This funtion is kind of non-intuitive in it's use.  To begin, one passes NULL as the second arguement.  It will return a pointer to the string of the first category in the file.  From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
    00081  *
    00082  * Returns a category on success, or NULL on failure/no-more-categories
    00083  */
    00084 char *ast_category_browse(struct ast_config *config, const char *prev);
    00085
    00086 /*! \brief Goes through variables
    00087  * Somewhat similar in intent as the ast_category_browse.
    00088  * List variables of config file category
    00089  *
    00090  * Returns ast_variable list on success, or NULL on failure
    00091  */
    00092 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
    00093
    00094 /*! \brief Gets a variable
    00095  * \param config which (opened) config to use
    00096  * \param category category under which the variable lies
    00097  * \param variable which variable you wish to get the data for
    00098  * Goes through a given config file in the given category and searches for the given variable
    00099  *
    00100  * Returns the variable value on success, or NULL if unable to find it.
    00101  */
    00102 char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
    00103
    00104 /*! \brief Retrieve a category if it exists
    00105  * \param config which config to use
    00106  * \param category_name name of the category you're looking for
    00107  * This will search through the categories within a given config file for a match.
    00108  *
    00109  * Returns pointer to category if found, NULL if not.
    00110  */
    00111 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
    00112
    00113 /*! \brief Check for category duplicates
    00114  * \param config which config to use
    00115  * \param category_name name of the category you're looking for
    00116  * This will search through the categories within a given config file for a match.
    00117  *
    00118  * Return non-zero if found
    00119  */
    00120 int ast_category_exist(const struct ast_config *config, const char *category_name);
    00121
    00122 /*! \brief Retrieve realtime configuration
    00123  * \param family which family/config to lookup
    00124  * This will use builtin configuration backends to look up a particular
    00125  * entity in realtime and return a variable list of its parameters.  Note
    00126  * that unlike the variables in ast_config, the resulting list of variables
    00127  * MUST be fred with ast_free_runtime() as there is no container.
    00128  */
    00129 struct ast_variable *ast_load_realtime(const char *family, ...);
    00130
    00131 /*! \brief Retrieve realtime configuration
    00132  * \param family which family/config to lookup
    00133  * This will use builtin configuration backends to look up a particular
    00134  * entity in realtime and return a variable list of its parameters. Unlike
    00135  * the ast_load_realtime, this function can return more than one entry and
    00136  * is thus stored inside a taditional ast_config structure rather than
    00137  * just returning a linked list of variables.
    00138  */
    00139 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
    00140
    00141 /*! \brief Update realtime configuration
    00142  * \param family which family/config to be updated
    00143  * \param keyfield which field to use as the key
    00144  * \param lookup which value to look for in the key field to match the entry.
    00145  * This function is used to update a parameter in realtime configuration space.
    00146  *
    00147  */
    00148 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
    00149
    00150 /*! \brief Check if realtime engine is configured for family
    00151  * returns 1 if family is configured in realtime and engine exists
    00152  * \param family which family/config to be checked
    00153 */
    00154 int ast_check_realtime(const char *family);
    00155
    00156 /*! \brief Free variable list
    00157  * \param var the linked list of variables to free
    00158  * This function frees a list of variables.
    00159  */
    00160 void ast_variables_destroy(struct ast_variable *var);
    00161
    00162 /*! \brief Register config engine */
    00163 int ast_config_engine_register(struct ast_config_engine *newconfig);
    00164
    00165 /*! \brief Deegister config engine */
    00166 int ast_config_engine_deregister(struct ast_config_engine *del);
    00167
    00168 int register_config_cli(void);
    00169 void read_config_maps(void);
    00170
    00171 struct ast_config *ast_config_new(void);
    00172 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
    00173 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
    00174
    00175 struct ast_category *ast_category_new(const char *name);
    00176 void ast_category_append(struct ast_config *config, struct ast_category *cat);
    00177 int ast_category_delete(struct ast_config *cfg, char *category);
    00178 void ast_category_destroy(struct ast_category *cat);
    00179 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
    00180 void ast_category_rename(struct ast_category *cat, const char *name);
    00181
    00182 struct ast_variable *ast_variable_new(const char *name, const char *value);
    00183 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
    00184
    00185 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
    00186
    00187 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg);
    00188
    00189 #if defined(__cplusplus) || defined(c_plusplus)
    00190 }
    00191 #endif
    00192
    00193 #endif /* _ASTERISK_CONFIG_H */