Wed Oct 28 11:45:37 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 "asterisk/utils.h"
00031 
00032 struct ast_config;
00033 
00034 struct ast_category;
00035 
00036 /*! Options for ast_config_load()
00037  */
00038 enum {
00039    /*! Load the configuration, including comments */
00040    CONFIG_FLAG_WITHCOMMENTS  = (1 << 0),
00041    /*! On a reload, give us a -1 if the file hasn't changed. */
00042    CONFIG_FLAG_FILEUNCHANGED = (1 << 1),
00043    /*! Don't attempt to cache mtime on this config file. */
00044    CONFIG_FLAG_NOCACHE       = (1 << 2),
00045 };
00046 
00047 #define  CONFIG_STATUS_FILEUNCHANGED   (void *)-1
00048 
00049 /*! \brief Structure for variables, used for configurations and for channel variables 
00050 */
00051 struct ast_variable {
00052    const char *name;
00053    const char *value;
00054    struct ast_variable *next;
00055 
00056    char *file;
00057 
00058    int lineno;
00059    int object;    /*!< 0 for variable, 1 for object */
00060    int blanklines;   /*!< Number of blanklines following entry */
00061    struct ast_comment *precomments;
00062    struct ast_comment *sameline;
00063    struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
00064    char stuff[0];
00065 };
00066 
00067 typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config, struct ast_flags flags, const char *suggested_include_file, const char *who_asked);
00068 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
00069 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
00070 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
00071 typedef int realtime_store(const char *database, const char *table, va_list ap);
00072 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
00073 
00074 /*! \brief Configuration engine structure, used to define realtime drivers */
00075 struct ast_config_engine {
00076    char *name;
00077    config_load_func *load_func;
00078    realtime_var_get *realtime_func;
00079    realtime_multi_get *realtime_multi_func;
00080    realtime_update *update_func;
00081    realtime_store *store_func;
00082    realtime_destroy *destroy_func;
00083    struct ast_config_engine *next;
00084 };
00085 
00086 /*! \brief Load a config file 
00087  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
00088  * Create a config structure from a given configuration file.
00089  * \param who_asked The module which is making this request.
00090  * \param flags Optional flags:
00091  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
00092  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
00093  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
00094  *
00095  * \return an ast_config data structure on success
00096  * \retval NULL on error
00097  */
00098 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
00099 
00100 #define ast_config_load(filename, flags)  ast_config_load2(filename, __FILE__, flags)
00101 
00102 /*! \brief Destroys a config 
00103  * \param config pointer to config data structure
00104  * Free memory associated with a given config
00105  *
00106  */
00107 void ast_config_destroy(struct ast_config *config);
00108 
00109 /*! \brief returns the root ast_variable of a config
00110  * \param config pointer to an ast_config data structure
00111  * \param cat name of the category for which you want the root
00112  *
00113  * Returns the category specified
00114  */
00115 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
00116 
00117 /*! \brief Goes through categories 
00118  * \param config Which config structure you wish to "browse"
00119  * \param prev A pointer to a previous category.
00120  * This function is kind of non-intuitive in it's use.  To begin, one passes NULL as the second argument.  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.
00121  *
00122  * \retval a category on success
00123  * \retval NULL on failure/no-more-categories
00124  */
00125 char *ast_category_browse(struct ast_config *config, const char *prev);
00126 
00127 /*! 
00128  * \brief Goes through variables
00129  * Somewhat similar in intent as the ast_category_browse.
00130  * List variables of config file category
00131  *
00132  * \retval ast_variable list on success
00133  * \retval NULL on failure
00134  */
00135 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
00136 
00137 /*!
00138  * \brief given a pointer to a category, return the root variable.
00139  * This is equivalent to ast_variable_browse(), but more efficient if we
00140  * already have the struct ast_category * (e.g. from ast_category_get())
00141  */
00142 struct ast_variable *ast_category_first(struct ast_category *cat);
00143 
00144 /*! 
00145  * \brief Gets a variable 
00146  * \param config which (opened) config to use
00147  * \param category category under which the variable lies
00148  * \param variable which variable you wish to get the data for
00149  * Goes through a given config file in the given category and searches for the given variable
00150  *
00151  * \retval The variable value on success 
00152  * \retval NULL if unable to find it.
00153  */
00154 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
00155 
00156 /*! 
00157  * \brief Retrieve a category if it exists
00158  * \param config which config to use
00159  * \param category_name name of the category you're looking for
00160  * This will search through the categories within a given config file for a match.
00161  *
00162  * \retval pointer to category if found
00163  * \retval NULL if not.
00164  */
00165 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
00166 
00167 /*! 
00168  * \brief Check for category duplicates 
00169  * \param config which config to use
00170  * \param category_name name of the category you're looking for
00171  * This will search through the categories within a given config file for a match.
00172  *
00173  * \return non-zero if found
00174  */
00175 int ast_category_exist(const struct ast_config *config, const char *category_name);
00176 
00177 /*! 
00178  * \brief Retrieve realtime configuration 
00179  * \param family which family/config to lookup
00180  * This will use builtin configuration backends to look up a particular 
00181  * entity in realtime and return a variable list of its parameters.  Note
00182  * that unlike the variables in ast_config, the resulting list of variables
00183  * MUST be freed with ast_variables_destroy() as there is no container.
00184  *
00185  * The difference between these two calls is that ast_load_realtime excludes
00186  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
00187  */
00188 struct ast_variable *ast_load_realtime(const char *family, ...);
00189 struct ast_variable *ast_load_realtime_all(const char *family, ...);
00190 
00191 /*! 
00192  * \brief Retrieve realtime configuration 
00193  * \param family which family/config to lookup
00194  * This will use builtin configuration backends to look up a particular 
00195  * entity in realtime and return a variable list of its parameters. Unlike
00196  * the ast_load_realtime, this function can return more than one entry and
00197  * is thus stored inside a taditional ast_config structure rather than 
00198  * just returning a linked list of variables.
00199  */
00200 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
00201 
00202 /*! 
00203  * \brief Update realtime configuration 
00204  * \param family which family/config to be updated
00205  * \param keyfield which field to use as the key
00206  * \param lookup which value to look for in the key field to match the entry.
00207  * This function is used to update a parameter in realtime configuration space.
00208  * \return Number of rows affected, or -1 on error.
00209  *
00210  */
00211 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
00212 
00213 /*! 
00214  * \brief Create realtime configuration 
00215  * \param family which family/config to be created
00216  * This function is used to create a parameter in realtime configuration space.
00217  * \return Number of rows affected, or -1 on error.
00218  * On the MySQL engine only, for reasons of backwards compatibility, the return
00219  * value is the insert ID.  This value is nonportable and may be changed in a
00220  * future version to match the other engines.
00221  *
00222  */
00223 int ast_store_realtime(const char *family, ...);
00224 
00225 /*! 
00226  * \brief Destroy realtime configuration 
00227  * \param family which family/config to be destroyed
00228  * \param keyfield which field to use as the key
00229  * \param lookup which value to look for in the key field to match the entry.
00230  * This function is used to destroy an entry in realtime configuration space.
00231  * Additional params are used as keys.
00232  * \return Number of rows affected, or -1 on error.
00233  *
00234  */
00235 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...);
00236 
00237 /*! 
00238  * \brief Check if realtime engine is configured for family 
00239  * \param family which family/config to be checked
00240  * \return 1 if family is configured in realtime and engine exists
00241 */
00242 int ast_check_realtime(const char *family);
00243 
00244 /*! \brief Check if there's any realtime engines loaded */
00245 int ast_realtime_enabled(void);
00246 
00247 /*! \brief Free variable list 
00248  * \param var the linked list of variables to free
00249  * This function frees a list of variables.
00250  */
00251 void ast_variables_destroy(struct ast_variable *var);
00252 
00253 /*! \brief Register config engine
00254  * \retval 1 Always
00255  */
00256 int ast_config_engine_register(struct ast_config_engine *newconfig);
00257 
00258 /*! \brief Deregister config engine
00259  * \retval 0 Always
00260  */
00261 int ast_config_engine_deregister(struct ast_config_engine *del);
00262 
00263 /*!\brief Exposed initialization method for core process
00264  * This method is intended for use only with the core initialization and is
00265  * not designed to be called from any user applications.
00266  */
00267 int register_config_cli(void);
00268 
00269 /*!\brief Exposed re-initialization method for core process
00270  * This method is intended for use only with the core re-initialization and is
00271  * not designed to be called from any user applications.
00272  */
00273 int read_config_maps(void);
00274 
00275 /*!\brief Create a new base configuration structure */
00276 struct ast_config *ast_config_new(void);
00277 
00278 /*!\brief Retrieve the current category name being built.
00279  * API for backend configuration engines while building a configuration set.
00280  */
00281 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
00282 
00283 /*!\brief Set the category within the configuration as being current.
00284  * API for backend configuration engines while building a configuration set.
00285  */
00286 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
00287 
00288 /*!\brief Retrieve a configuration variable within the configuration set.
00289  * Retrieves the named variable \p var within category \p cat of configuration
00290  * set \p cfg.  If not found, attempts to retrieve the named variable \p var
00291  * from within category \em general.
00292  * \return Value of \p var, or NULL if not found.
00293  */
00294 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
00295 
00296 /*!\brief Create a category structure */
00297 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
00298 void ast_category_append(struct ast_config *config, struct ast_category *cat);
00299 
00300 /*! 
00301  * \brief Inserts new category
00302  * \param config which config to use
00303  * \param cat newly created category to insert
00304  * \param match which category to insert above
00305  * This function is used to insert a new category above another category
00306  * matching the match parameter.
00307  */
00308 void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
00309 int ast_category_delete(struct ast_config *cfg, const char *category);
00310 
00311 /*!\brief Removes and destroys all variables within a category
00312  * \retval 0 if the category was found and emptied
00313  * \retval -1 if the category was not found
00314  */
00315 int ast_category_empty(struct ast_config *cfg, const char *category);
00316 void ast_category_destroy(struct ast_category *cat);
00317 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
00318 void ast_category_rename(struct ast_category *cat, const char *name);
00319 
00320 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
00321 struct ast_config_include *ast_include_new(struct ast_config *conf, const char *from_file, const char *included_file, int is_exec, const char *exec_file, int from_lineno, char *real_included_file_name, int real_included_file_name_size);
00322 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
00323 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
00324 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
00325 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
00326 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
00327 int ast_variable_update(struct ast_category *category, const char *variable, 
00328                   const char *value, const char *match, unsigned int object);
00329 
00330 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
00331 
00332 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, struct ast_flags flags, const char *suggested_incl_file, const char *who_asked);
00333 
00334 /*! \brief Support code to parse config file arguments
00335  *
00336  * The function ast_parse_arg() provides a generic interface to parse
00337  * strings (e.g. numbers, network addresses and so on) in a flexible
00338  * way, e.g. by doing proper error and bound checks, provide default
00339  * values, and so on.
00340  * The function (described later) takes a string as an argument,
00341  * a set of flags to specify the result format and checks to perform,
00342  * a pointer to the result, and optionally some additional arguments.
00343  * It returns 0 on success, != 0 otherwise.
00344  *
00345  */
00346 enum ast_parse_flags {
00347    /* low 4 bits of flags are used for the operand type */
00348    PARSE_TYPE  =  0x000f,
00349    /* numeric types, with optional default value and bound checks.
00350     * Additional arguments are passed by value.
00351     */
00352    PARSE_INT32 =  0x0001,
00353    PARSE_UINT32   =  0x0002,
00354    PARSE_DOUBLE   =  0x0003,
00355 #if 0 /* not supported yet */
00356    PARSE_INT16 =  0x0004,
00357    PARSE_UINT16   =  0x0005,
00358 #endif
00359    /* Returns a struct sockaddr_in, with optional default value
00360     * (passed by reference) and port handling (accept, ignore,
00361     * require, forbid). The format is 'host.name[:port]'
00362     */
00363    PARSE_INADDR   =  0x000f,
00364 
00365    /* Other data types can be added as needed */
00366 
00367    /* If PARSE_DEFAULT is set, next argument is a default value
00368     * which is returned in case of error. The argument is passed
00369     * by value in case of numeric types, by reference in other cases.
00370     */
00371    PARSE_DEFAULT  =  0x0010,  /* assign default on error */
00372 
00373    /* Request a range check, applicable to numbers. Two additional
00374     * arguments are passed by value, specifying the low-high end of
00375     * the range (inclusive). An error is returned if the value
00376     * is outside or inside the range, respectively.
00377     */
00378    PARSE_IN_RANGE =  0x0020,  /* accept values inside a range */
00379    PARSE_OUT_RANGE = 0x0040,  /* accept values outside a range */
00380 
00381    /* Port handling, for sockaddr_in. accept/ignore/require/forbid
00382     * port number after the hostname or address.
00383     */
00384    PARSE_PORT_MASK = 0x0300, /* 0x000: accept port if present */
00385    PARSE_PORT_IGNORE =  0x0100, /* 0x100: ignore port if present */
00386    PARSE_PORT_REQUIRE = 0x0200, /* 0x200: require port number */
00387    PARSE_PORT_FORBID =  0x0300, /* 0x100: forbid port number */
00388 };
00389 
00390 /*! \brief The argument parsing routine.
00391  * \param arg the string to parse. It is not modified.
00392  * \param flags combination of ast_parse_flags to specify the
00393  * return type and additional checks.
00394  * \param result pointer to the result. NULL is valid here, and can
00395  * be used to perform only the validity checks.
00396  * \param ... extra arguments are required according to flags.
00397  * \retval 0 in case of success, != 0 otherwise.
00398  * \retval result returns the parsed value in case of success,
00399  * the default value in case of error, or it is left unchanged
00400  * in case of error and no default specified. Note that in certain
00401  * cases (e.g. sockaddr_in, with multi-field return values) some
00402  * of the fields in result may be changed even if an error occurs.
00403  *
00404  * Examples of use:
00405  * ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
00406  *    &a, -1000, 1000); 
00407  *              returns 0, a = 223
00408  * ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
00409  *    &a, 9999, 10, 100);
00410  *              returns 1, a = 9999
00411  *      ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
00412  *    returns 1, b unchanged
00413  *      ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
00414  *    returns 0, sa contains address and port
00415  *      ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
00416  *    returns 1 because port is missing, sa contains address
00417  */
00418 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
00419         void *result, ...);
00420 
00421 /*
00422  * Parsing config file options in C is slightly annoying because we cannot use
00423  * string in a switch() statement, yet we need a similar behaviour, with many
00424  * branches and a break on a matching one.
00425  * The following somehow simplifies the job: we create a block using
00426  * the   CV_START and CV_END macros, and then within the block we can run
00427  * actions such as "if (condition) { body; break; }"
00428  * Additional macros are present to run simple functions (e.g. ast_copy_string)
00429  * or to pass arguments to ast_parse_arg()
00430  *
00431  * As an example:
00432 
00433    CV_START(v->name, v->value);  // start the block
00434    CV_STR("foo", x_foo);      // static string
00435    CV_DSTR("bar", y_bar);     // malloc'ed string
00436    CV_F("bar", ...);    // call a generic function
00437    CV_END;           // end the block
00438  */
00439 
00440 /*! \brief the macro to open a block for variable parsing */
00441 #define CV_START(__in_var, __in_val)      \
00442    do {              \
00443       const char *__var = __in_var; \
00444       const char *__val = __in_val;
00445 
00446 /*! \brief close a variable parsing block */
00447 #define  CV_END         } while (0)
00448 
00449 /*! \brief call a generic function if the name matches. */
00450 #define  CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
00451 
00452 /*! \brief helper macros to assign the value to a BOOL, UINT, static string and
00453  * dynamic string
00454  */
00455 #define  CV_BOOL(__x, __dst)  CV_F(__x, (__dst) = ast_true(__val) )
00456 #define CV_UINT(__x, __dst)   CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
00457 #define CV_STR(__x, __dst) CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
00458 #define CV_DSTR(__x, __dst)   CV_F(__x, if (__dst) ast_free(__dst); __dst = ast_strdup(__val))
00459 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
00460 
00461 #if defined(__cplusplus) || defined(c_plusplus)
00462 }
00463 #endif
00464 
00465 #endif /* _ASTERISK_CONFIG_H */

Generated on Wed Oct 28 11:45:37 2009 for Asterisk - the Open Source PBX by  doxygen 1.5.6