Sat Aug 6 00:39:28 2011

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, int withcomments);
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 struct ast_config *ast_config_load_with_comments(const char *filename);
00070 
00071 /*! \brief Destroys a config 
00072  * \param config pointer to config data structure
00073  * Free memory associated with a given config
00074  *
00075  */
00076 void ast_config_destroy(struct ast_config *config);
00077 
00078 /*! \brief returns the root ast_variable of a config
00079  * \param config pointer to an ast_config data structure
00080  * \param cat name of the category for which you want the root
00081  *
00082  * Returns the category specified
00083  */
00084 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
00085 
00086 /*! \brief Goes through categories 
00087  * \param config Which config structure you wish to "browse"
00088  * \param prev A pointer to a previous category.
00089  * 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.
00090  *
00091  * Returns a category on success, or NULL on failure/no-more-categories
00092  */
00093 char *ast_category_browse(struct ast_config *config, const char *prev);
00094 
00095 /*! \brief Goes through variables
00096  * Somewhat similar in intent as the ast_category_browse.
00097  * List variables of config file category
00098  *
00099  * Returns ast_variable list on success, or NULL on failure
00100  */
00101 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
00102 
00103 //! Iterates through variables
00104 /*!
00105  * Somewhat similar in intent as the ast_category_browse.  The prev variable MUST be an actual pointer to an actual variable (such as one obtained by using ast_variable_browse() or ast_variable_next() itself).
00106  * List variables of config file
00107  * Returns next variable on the list, or NULL on failure
00108  */
00109 struct ast_variable *ast_variable_next(struct ast_config *config, char *category,struct ast_variable *prev);
00110 
00111 /*! \brief Gets a variable 
00112  * \param config which (opened) config to use
00113  * \param category category under which the variable lies
00114  * \param variable which variable you wish to get the data for
00115  * Goes through a given config file in the given category and searches for the given variable
00116  *
00117  * Returns the variable value on success, or NULL if unable to find it.
00118  */
00119 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
00120 
00121 /*! \brief Retrieve a category if it exists
00122  * \param config which config to use
00123  * \param category_name name of the category you're looking for
00124  * This will search through the categories within a given config file for a match.
00125  *
00126  * Returns pointer to category if found, NULL if not.
00127  */
00128 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
00129 
00130 /*! \brief Check for category duplicates 
00131  * \param config which config to use
00132  * \param category_name name of the category you're looking for
00133  * This will search through the categories within a given config file for a match.
00134  *
00135  * Return non-zero if found
00136  */
00137 int ast_category_exist(const struct ast_config *config, const char *category_name);
00138 
00139 /*! \brief Retrieve realtime configuration 
00140  * \param family which family/config to lookup
00141  * This will use builtin configuration backends to look up a particular 
00142  * entity in realtime and return a variable list of its parameters.  Note
00143  * that unlike the variables in ast_config, the resulting list of variables
00144  * MUST be freed with ast_variables_destroy() as there is no container.
00145  */
00146 struct ast_variable *ast_load_realtime(const char *family, ...);
00147 
00148 /*! \brief Retrieve realtime configuration 
00149  * \param family which family/config to lookup
00150  * This will use builtin configuration backends to look up a particular 
00151  * entity in realtime and return a variable list of its parameters. Unlike
00152  * the ast_load_realtime, this function can return more than one entry and
00153  * is thus stored inside a taditional ast_config structure rather than 
00154  * just returning a linked list of variables.
00155  */
00156 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
00157 
00158 /*! \brief Update realtime configuration 
00159  * \param family which family/config to be updated
00160  * \param keyfield which field to use as the key
00161  * \param lookup which value to look for in the key field to match the entry.
00162  * This function is used to update a parameter in realtime configuration space.
00163  * \return Number of rows affected, or -1 on error.
00164  */
00165 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
00166 
00167 /*! \brief Check if realtime engine is configured for family 
00168  * returns 1 if family is configured in realtime and engine exists
00169  * \param family which family/config to be checked
00170 */
00171 int ast_check_realtime(const char *family);
00172 
00173 /*! \brief Check if realtime engine is enabled
00174  * returns 1 if realtime is enabled
00175  */
00176 int ast_realtime_enabled(void);
00177 
00178 /*! \brief Free variable list 
00179  * \param var the linked list of variables to free
00180  * This function frees a list of variables.
00181  */
00182 void ast_variables_destroy(struct ast_variable *var);
00183 
00184 /*! \brief Register config engine */
00185 int ast_config_engine_register(struct ast_config_engine *newconfig);
00186 
00187 /*! \brief Deegister config engine */
00188 int ast_config_engine_deregister(struct ast_config_engine *del);
00189 
00190 int register_config_cli(void);
00191 int read_config_maps(void);
00192 
00193 struct ast_config *ast_config_new(void);
00194 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
00195 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
00196 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
00197 
00198 struct ast_category *ast_category_new(const char *name);
00199 void ast_category_append(struct ast_config *config, struct ast_category *cat);
00200 int ast_category_delete(struct ast_config *cfg, char *category);
00201 void ast_category_destroy(struct ast_category *cat);
00202 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
00203 void ast_category_rename(struct ast_category *cat, const char *name);
00204 
00205 struct ast_variable *ast_variable_new(const char *name, const char *value);
00206 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
00207 int ast_variable_delete(struct ast_category *category, char *variable, char *match);
00208 int ast_variable_update(struct ast_category *category, const char *variable, 
00209    const char *value, const char *match, unsigned int object);
00210 
00211 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
00212 
00213 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, int withcomments);
00214 
00215 #if defined(__cplusplus) || defined(c_plusplus)
00216 }
00217 #endif
00218 
00219 #endif /* _ASTERISK_CONFIG_H */

Generated on Sat Aug 6 00:39:28 2011 for Asterisk - the Open Source PBX by  doxygen 1.4.7