Sat Mar 10 01:54:15 2012

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 #include "asterisk/inline_api.h"
00032 
00033 struct ast_config;
00034 
00035 struct ast_category;
00036 
00037 /*! Options for ast_config_load()
00038  */
00039 enum {
00040    /*! Load the configuration, including comments */
00041    CONFIG_FLAG_WITHCOMMENTS  = (1 << 0),
00042    /*! On a reload, give us a -1 if the file hasn't changed. */
00043    CONFIG_FLAG_FILEUNCHANGED = (1 << 1),
00044    /*! Don't attempt to cache mtime on this config file. */
00045    CONFIG_FLAG_NOCACHE       = (1 << 2),
00046    /*! Don't attempt to load from realtime (typically called from a realtime driver dependency) */
00047    CONFIG_FLAG_NOREALTIME    = (1 << 3),
00048 };
00049 
00050 #define  CONFIG_STATUS_FILEMISSING  (void *)0
00051 #define  CONFIG_STATUS_FILEUNCHANGED   (void *)-1
00052 #define  CONFIG_STATUS_FILEINVALID  (void *)-2
00053 
00054 /*!
00055  * \brief Types used in ast_realtime_require_field
00056  */
00057 typedef enum {
00058    RQ_INTEGER1,
00059    RQ_UINTEGER1,
00060    RQ_INTEGER2,
00061    RQ_UINTEGER2,
00062    RQ_INTEGER3,
00063    RQ_UINTEGER3,
00064    RQ_INTEGER4,
00065    RQ_UINTEGER4,
00066    RQ_INTEGER8,
00067    RQ_UINTEGER8,
00068    RQ_CHAR,
00069    RQ_FLOAT,
00070    RQ_DATE,
00071    RQ_DATETIME,
00072 } require_type;
00073 
00074 /*! \brief Structure for variables, used for configurations and for channel variables */
00075 struct ast_variable {
00076    /*! Variable name.  Stored in stuff[] at struct end. */
00077    const char *name;
00078    /*! Variable value.  Stored in stuff[] at struct end. */
00079    const char *value;
00080 
00081    /*! Next node in the list. */
00082    struct ast_variable *next;
00083 
00084    /*! Filename where variable found.  Stored in stuff[] at struct end. */
00085    const char *file;
00086 
00087    int lineno;
00088    int object;    /*!< 0 for variable, 1 for object */
00089    int blanklines;   /*!< Number of blanklines following entry */
00090    struct ast_comment *precomments;
00091    struct ast_comment *sameline;
00092    struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
00093    /*!
00094     * \brief Contents of file, name, and value in that order stuffed here.
00095     * \note File must be stuffed before name because of ast_include_rename().
00096     */
00097    char stuff[0];
00098 };
00099 
00100 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);
00101 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
00102 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
00103 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
00104 typedef int realtime_update2(const char *database, const char *table, va_list ap);
00105 typedef int realtime_store(const char *database, const char *table, va_list ap);
00106 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
00107 
00108 /*!
00109  * \brief Function pointer called to ensure database schema is properly configured for realtime use
00110  * \since 1.6.1
00111  */
00112 typedef int realtime_require(const char *database, const char *table, va_list ap);
00113 
00114 /*!
00115  * \brief Function pointer called to clear the database cache and free resources used for such
00116  * \since 1.6.1
00117  */
00118 typedef int realtime_unload(const char *database, const char *table);
00119 
00120 /*! \brief Configuration engine structure, used to define realtime drivers */
00121 struct ast_config_engine {
00122    char *name;
00123    config_load_func *load_func;
00124    realtime_var_get *realtime_func;
00125    realtime_multi_get *realtime_multi_func;
00126    realtime_update *update_func;
00127    realtime_update2 *update2_func;
00128    realtime_store *store_func;
00129    realtime_destroy *destroy_func;
00130    realtime_require *require_func;
00131    realtime_unload *unload_func;
00132    struct ast_config_engine *next;
00133 };
00134 
00135 /*!
00136  * \brief Load a config file
00137  *
00138  * \param filename path of file to open.  If no preceding '/' character,
00139  * path is considered relative to AST_CONFIG_DIR
00140  * \param who_asked The module which is making this request.
00141  * \param flags Optional flags:
00142  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
00143  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
00144  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
00145  *
00146  * \details
00147  * Create a config structure from a given configuration file.
00148  *
00149  * \return an ast_config data structure on success
00150  * \retval NULL on error
00151  */
00152 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
00153 
00154 /*!
00155  * \brief Load a config file
00156  *
00157  * \param filename path of file to open.  If no preceding '/' character,
00158  * path is considered relative to AST_CONFIG_DIR
00159  * \param flags Optional flags:
00160  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
00161  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
00162  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
00163  *
00164  * \details
00165  * Create a config structure from a given configuration file.
00166  *
00167  * \return an ast_config data structure on success
00168  * \retval NULL on error
00169  */
00170 #define ast_config_load(filename, flags)  ast_config_load2(filename, AST_MODULE, flags)
00171 
00172 /*!
00173  * \brief Destroys a config
00174  *
00175  * \param config pointer to config data structure
00176  *
00177  * \details
00178  * Free memory associated with a given config
00179  */
00180 void ast_config_destroy(struct ast_config *config);
00181 
00182 /*!
00183  * \brief returns the root ast_variable of a config
00184  *
00185  * \param config pointer to an ast_config data structure
00186  * \param cat name of the category for which you want the root
00187  *
00188  * \return the category specified
00189  */
00190 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
00191 
00192 /*!
00193  * \brief Goes through categories
00194  *
00195  * \param config Which config structure you wish to "browse"
00196  * \param prev A pointer to a previous category.
00197  *
00198  * \details
00199  * This function is kind of non-intuitive in it's use.
00200  * To begin, one passes NULL as the second argument.
00201  * It will return a pointer to the string of the first category in the file.
00202  * From here on after, one must then pass the previous usage's return value
00203  * as the second pointer, and it will return a pointer to the category name
00204  * afterwards.
00205  *
00206  * \retval a category on success
00207  * \retval NULL on failure/no-more-categories
00208  */
00209 char *ast_category_browse(struct ast_config *config, const char *prev);
00210 
00211 /*!
00212  * \brief Goes through variables
00213  *
00214  * \details
00215  * Somewhat similar in intent as the ast_category_browse.
00216  * List variables of config file category
00217  *
00218  * \retval ast_variable list on success
00219  * \retval NULL on failure
00220  */
00221 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
00222 
00223 /*!
00224  * \brief given a pointer to a category, return the root variable.
00225  *
00226  * \details
00227  * This is equivalent to ast_variable_browse(), but more efficient if we
00228  * already have the struct ast_category * (e.g. from ast_category_get())
00229  */
00230 struct ast_variable *ast_category_first(struct ast_category *cat);
00231 
00232 /*!
00233  * \brief Gets a variable
00234  *
00235  * \param config which (opened) config to use
00236  * \param category category under which the variable lies
00237  * \param variable which variable you wish to get the data for
00238  *
00239  * \details
00240  * Goes through a given config file in the given category and searches for the given variable
00241  *
00242  * \retval The variable value on success
00243  * \retval NULL if unable to find it.
00244  */
00245 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
00246 
00247 /*!
00248  * \brief Retrieve a category if it exists
00249  *
00250  * \param config which config to use
00251  * \param category_name name of the category you're looking for
00252  *
00253  * \details
00254  * This will search through the categories within a given config file for a match.
00255  *
00256  * \retval pointer to category if found
00257  * \retval NULL if not.
00258  */
00259 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
00260 
00261 /*!
00262  * \brief Check for category duplicates
00263  *
00264  * \param config which config to use
00265  * \param category_name name of the category you're looking for
00266  *
00267  * \details
00268  * This will search through the categories within a given config file for a match.
00269  *
00270  * \return non-zero if found
00271  */
00272 int ast_category_exist(const struct ast_config *config, const char *category_name);
00273 
00274 /*!
00275  * \brief Retrieve realtime configuration
00276  *
00277  * \param family which family/config to lookup
00278  *
00279  * \details
00280  * This will use builtin configuration backends to look up a particular
00281  * entity in realtime and return a variable list of its parameters.
00282  *
00283  * \note
00284  * Unlike the variables in ast_config, the resulting list of variables
00285  * MUST be freed with ast_variables_destroy() as there is no container.
00286  *
00287  * \note
00288  * The difference between these two calls is that ast_load_realtime excludes
00289  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
00290  *
00291  * \note
00292  * You should use the constant SENTINEL to terminate arguments, in
00293  * order to preserve cross-platform compatibility.
00294  */
00295 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
00296 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
00297 
00298 /*!
00299  * \brief Release any resources cached for a realtime family
00300  * \since 1.6.1
00301  *
00302  * \param family which family/config to destroy
00303  *
00304  * \details
00305  * Various backends may cache attributes about a realtime data storage
00306  * facility; on reload, a front end resource may request to purge that cache.
00307  *
00308  * \retval 0 If any cache was purged
00309  * \retval -1 If no cache was found
00310  */
00311 int ast_unload_realtime(const char *family);
00312 
00313 /*!
00314  * \brief Inform realtime what fields that may be stored
00315  * \since 1.6.1
00316  *
00317  * \param family which family/config is referenced
00318  *
00319  * \details
00320  * This will inform builtin configuration backends that particular fields
00321  * may be updated during the use of that configuration section.  This is
00322  * mainly to be used during startup routines, to ensure that various fields
00323  * exist in the backend.  The backends may take various actions, such as
00324  * creating new fields in the data store or warning the administrator that
00325  * new fields may need to be created, in order to ensure proper function.
00326  *
00327  * The arguments are specified in groups of 3:  column name, column type,
00328  * and column size.  The column types are specified as integer constants,
00329  * defined by the enum require_type.  Note that the size is specified as
00330  * the number of equivalent character fields that a field may take up, even
00331  * if a field is otherwise specified as an integer type.  This is due to
00332  * the fact that some fields have historically been specified as character
00333  * types, even if they contained integer values.
00334  *
00335  * A family should always specify its fields to the minimum necessary
00336  * requirements to fulfill all possible values (within reason; for example,
00337  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
00338  * Even though values above 32767 seconds are possible, they are unlikely
00339  * to be useful, and we should not complain about that size).
00340  *
00341  * \retval 0 Required fields met specified standards
00342  * \retval -1 One or more fields was missing or insufficient
00343  *
00344  * \note You should use the constant SENTINEL to terminate arguments, in
00345  * order to preserve cross-platform compatibility.
00346  */
00347 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
00348 
00349 /*!
00350  * \brief Retrieve realtime configuration
00351  *
00352  * \param family which family/config to lookup
00353  *
00354  * \details
00355  * This will use builtin configuration backends to look up a particular
00356  * entity in realtime and return a variable list of its parameters. Unlike
00357  * the ast_load_realtime, this function can return more than one entry and
00358  * is thus stored inside a traditional ast_config structure rather than
00359  * just returning a linked list of variables.
00360  *
00361  * \return An ast_config with one or more results
00362  * \retval NULL Error or no results returned
00363  *
00364  * \note You should use the constant SENTINEL to terminate arguments, in
00365  * order to preserve cross-platform compatibility.
00366  */
00367 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
00368 
00369 /*!
00370  * \brief Update realtime configuration
00371  *
00372  * \param family which family/config to be updated
00373  * \param keyfield which field to use as the key
00374  * \param lookup which value to look for in the key field to match the entry.
00375  *
00376  * \details
00377  * This function is used to update a parameter in realtime configuration space.
00378  *
00379  * \return Number of rows affected, or -1 on error.
00380  *
00381  * \note You should use the constant SENTINEL to terminate arguments, in
00382  * order to preserve cross-platform compatibility.
00383  */
00384 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
00385 
00386 /*!
00387  * \brief Update realtime configuration
00388  *
00389  * \param family which family/config to be updated
00390  *
00391  * \details
00392  * This function is used to update a parameter in realtime configuration space.
00393  * It includes the ability to lookup a row based upon multiple key criteria.
00394  * As a result, this function includes two sentinel values, one to terminate
00395  * lookup values and the other to terminate the listing of fields to update.
00396  *
00397  * \return Number of rows affected, or -1 on error.
00398  *
00399  * \note You should use the constant SENTINEL to terminate arguments, in
00400  * order to preserve cross-platform compatibility.
00401  */
00402 int ast_update2_realtime(const char *family, ...) attribute_sentinel;
00403 
00404 /*!
00405  * \brief Create realtime configuration
00406  *
00407  * \param family which family/config to be created
00408  *
00409  * \details
00410  * This function is used to create a parameter in realtime configuration space.
00411  *
00412  * \return Number of rows affected, or -1 on error.
00413  *
00414  * \note
00415  * On the MySQL engine only, for reasons of backwards compatibility, the return
00416  * value is the insert ID.  This value is nonportable and may be changed in a
00417  * future version to match the other engines.
00418  *
00419  * \note You should use the constant SENTINEL to terminate arguments, in
00420  * order to preserve cross-platform compatibility.
00421  */
00422 int ast_store_realtime(const char *family, ...) attribute_sentinel;
00423 
00424 /*!
00425  * \brief Destroy realtime configuration
00426  *
00427  * \param family which family/config to be destroyed
00428  * \param keyfield which field to use as the key
00429  * \param lookup which value to look for in the key field to match the entry.
00430  *
00431  * \details
00432  * This function is used to destroy an entry in realtime configuration space.
00433  * Additional params are used as keys.
00434  *
00435  * \return Number of rows affected, or -1 on error.
00436  *
00437  * \note You should use the constant SENTINEL to terminate arguments, in
00438  * order to preserve cross-platform compatibility.
00439  */
00440 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
00441 
00442 /*!
00443  * \brief Check if realtime engine is configured for family
00444  * \param family which family/config to be checked
00445  * \return 1 if family is configured in realtime and engine exists
00446  */
00447 int ast_check_realtime(const char *family);
00448 
00449 /*! \brief Check if there's any realtime engines loaded */
00450 int ast_realtime_enabled(void);
00451 
00452 /*!
00453  * \brief Duplicate variable list
00454  * \param var the linked list of variables to clone
00455  * \return A duplicated list which you'll need to free with
00456  * ast_variables_destroy or NULL when out of memory.
00457  *
00458  * \note Do not depend on this to copy more than just name, value and filename
00459  * (the arguments to ast_variables_new).
00460  */
00461 struct ast_variable *ast_variables_dup(struct ast_variable *var);
00462 
00463 /*!
00464  * \brief Free variable list
00465  * \param var the linked list of variables to free
00466  *
00467  * \details
00468  * This function frees a list of variables.
00469  */
00470 void ast_variables_destroy(struct ast_variable *var);
00471 
00472 /*!
00473  * \brief Register config engine
00474  * \retval 1 Always
00475  */
00476 int ast_config_engine_register(struct ast_config_engine *newconfig);
00477 
00478 /*!
00479  * \brief Deregister config engine
00480  * \retval 0 Always
00481  */
00482 int ast_config_engine_deregister(struct ast_config_engine *del);
00483 
00484 /*!
00485  * \brief Exposed initialization method for core process
00486  *
00487  * \details
00488  * This method is intended for use only with the core initialization and is
00489  * not designed to be called from any user applications.
00490  */
00491 int register_config_cli(void);
00492 
00493 /*!
00494  * \brief Exposed re-initialization method for core process
00495  *
00496  * \details
00497  * This method is intended for use only with the core re-initialization and is
00498  * not designed to be called from any user applications.
00499  */
00500 int read_config_maps(void);
00501 
00502 /*! \brief Create a new base configuration structure */
00503 struct ast_config *ast_config_new(void);
00504 
00505 /*!
00506  * \brief Retrieve the current category name being built.
00507  *
00508  * \details
00509  * API for backend configuration engines while building a configuration set.
00510  */
00511 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
00512 
00513 /*!
00514  * \brief Set the category within the configuration as being current.
00515  *
00516  * \details
00517  * API for backend configuration engines while building a configuration set.
00518  */
00519 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
00520 
00521 /*!
00522  * \brief Retrieve a configuration variable within the configuration set.
00523  *
00524  * \details
00525  * Retrieves the named variable \p var within category \p cat of configuration
00526  * set \p cfg.  If not found, attempts to retrieve the named variable \p var
00527  * from within category \em general.
00528  *
00529  * \return Value of \p var, or NULL if not found.
00530  */
00531 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
00532 
00533 /*! \brief Create a category structure */
00534 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
00535 void ast_category_append(struct ast_config *config, struct ast_category *cat);
00536 
00537 /*!
00538  * \brief Inserts new category
00539  * 
00540  * \param config which config to use
00541  * \param cat newly created category to insert
00542  * \param match which category to insert above
00543  *
00544  * \details
00545  * This function is used to insert a new category above another category
00546  * matching the match parameter.
00547  */
00548 void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
00549 int ast_category_delete(struct ast_config *cfg, const char *category);
00550 
00551 /*!
00552  * \brief Removes and destroys all variables within a category
00553  * \retval 0 if the category was found and emptied
00554  * \retval -1 if the category was not found
00555  */
00556 int ast_category_empty(struct ast_config *cfg, const char *category);
00557 void ast_category_destroy(struct ast_category *cat);
00558 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
00559 void ast_category_rename(struct ast_category *cat, const char *name);
00560 
00561 #ifdef MALLOC_DEBUG
00562 struct ast_variable *_ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno);
00563 #define ast_variable_new(a, b, c) _ast_variable_new(a, b, c, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00564 #else
00565 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
00566 #endif
00567 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);
00568 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
00569 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
00570 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
00571 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
00572 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
00573 
00574 /*!
00575  * \brief Update variable value within a config
00576  *
00577  * \param category Category element within the config
00578  * \param variable Name of the variable to change
00579  * \param value New value of the variable
00580  * \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
00581  * \param object Boolean of whether to make the new variable an object
00582  *
00583  * \return 0 on success or -1 on failure.
00584  */
00585 int ast_variable_update(struct ast_category *category, const char *variable,
00586                   const char *value, const char *match, unsigned int object);
00587 
00588 int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
00589 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator) __attribute__((deprecated));
00590 
00591 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);
00592 
00593 /*!
00594  * \brief Support code to parse config file arguments
00595  *
00596  * \details
00597  * The function ast_parse_arg() provides a generic interface to parse
00598  * strings (e.g. numbers, network addresses and so on) in a flexible
00599  * way, e.g. by doing proper error and bound checks, provide default
00600  * values, and so on.
00601  * The function (described later) takes a string as an argument,
00602  * a set of flags to specify the result format and checks to perform,
00603  * a pointer to the result, and optionally some additional arguments.
00604  *
00605  * \return It returns 0 on success, != 0 otherwise.
00606  */
00607 enum ast_parse_flags {
00608    /* low 4 bits of flags are used for the operand type */
00609    PARSE_TYPE  =  0x000f,
00610    /* numeric types, with optional default value and bound checks.
00611     * Additional arguments are passed by value.
00612     */
00613    PARSE_INT32 =  0x0001,
00614    PARSE_UINT32   =  0x0002,
00615    PARSE_DOUBLE   =  0x0003,
00616 #if 0 /* not supported yet */
00617    PARSE_INT16 =  0x0004,
00618    PARSE_UINT16   =  0x0005,
00619 #endif
00620 
00621    /* Returns a struct ast_sockaddr, with optional default value
00622     * (passed by reference) and port handling (accept, ignore,
00623     * require, forbid). The format is 'ipaddress[:port]'. IPv6 address
00624     * literals need square brackets around them if a port is specified.
00625     */
00626    PARSE_ADDR  =  0x000e,
00627 
00628    /* Returns a struct sockaddr_in, with optional default value
00629     * (passed by reference) and port handling (accept, ignore,
00630     * require, forbid). The format is 'host.name[:port]'
00631     */
00632    PARSE_INADDR   =  0x000f,
00633 
00634    /* Other data types can be added as needed */
00635 
00636    /* If PARSE_DEFAULT is set, next argument is a default value
00637     * which is returned in case of error. The argument is passed
00638     * by value in case of numeric types, by reference in other cases.
00639     */
00640    PARSE_DEFAULT  =  0x0010,  /* assign default on error */
00641 
00642    /* Request a range check, applicable to numbers. Two additional
00643     * arguments are passed by value, specifying the low-high end of
00644     * the range (inclusive). An error is returned if the value
00645     * is outside or inside the range, respectively.
00646     */
00647    PARSE_IN_RANGE =  0x0020,  /* accept values inside a range */
00648    PARSE_OUT_RANGE = 0x0040,  /* accept values outside a range */
00649 
00650    /* Port handling, for ast_sockaddr. accept/ignore/require/forbid
00651     * port number after the hostname or address.
00652     */
00653    PARSE_PORT_MASK = 0x0300, /* 0x000: accept port if present */
00654    PARSE_PORT_IGNORE =  0x0100, /* 0x100: ignore port if present */
00655    PARSE_PORT_REQUIRE = 0x0200, /* 0x200: require port number */
00656    PARSE_PORT_FORBID =  0x0300, /* 0x100: forbid port number */
00657 };
00658 
00659 /*!
00660  * \brief The argument parsing routine.
00661  *
00662  * \param arg the string to parse. It is not modified.
00663  * \param flags combination of ast_parse_flags to specify the
00664  * return type and additional checks.
00665  * \param result pointer to the result. NULL is valid here, and can
00666  * be used to perform only the validity checks.
00667  * \param ... extra arguments are required according to flags.
00668  *
00669  * \retval 0 in case of success, != 0 otherwise.
00670  * \retval result returns the parsed value in case of success,
00671  * the default value in case of error, or it is left unchanged
00672  * in case of error and no default specified. Note that in certain
00673  * cases (e.g. sockaddr_in, with multi-field return values) some
00674  * of the fields in result may be changed even if an error occurs.
00675  *
00676  * \details
00677  * Examples of use:
00678  * ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
00679  *    &a, -1000, 1000);
00680  *              returns 0, a = 223
00681  * ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
00682  *    &a, 9999, 10, 100);
00683  *              returns 1, a = 9999
00684  *      ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
00685  *    returns 1, b unchanged
00686  *      ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
00687  *    returns 0, sa contains address and port
00688  *      ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
00689  *    returns 1 because port is missing, sa contains address
00690  */
00691 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
00692         void *result, ...);
00693 
00694 /*
00695  * Parsing config file options in C is slightly annoying because we cannot use
00696  * string in a switch() statement, yet we need a similar behaviour, with many
00697  * branches and a break on a matching one.
00698  * The following somehow simplifies the job: we create a block using
00699  * the   CV_START and CV_END macros, and then within the block we can run
00700  * actions such as "if (condition) { body; break; }"
00701  * Additional macros are present to run simple functions (e.g. ast_copy_string)
00702  * or to pass arguments to ast_parse_arg()
00703  *
00704  * As an example:
00705 
00706    CV_START(v->name, v->value);  // start the block
00707    CV_STR("foo", x_foo);      // static string
00708    CV_DSTR("bar", y_bar);     // malloc'ed string
00709    CV_F("bar", ...);    // call a generic function
00710    CV_END;           // end the block
00711  */
00712 
00713 /*! \brief the macro to open a block for variable parsing */
00714 #define CV_START(__in_var, __in_val)      \
00715    do {              \
00716       const char *__var = __in_var; \
00717       const char *__val = __in_val;
00718 
00719 /*! \brief close a variable parsing block */
00720 #define  CV_END         } while (0)
00721 
00722 /*! \brief call a generic function if the name matches. */
00723 #define  CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
00724 
00725 /*!
00726  * \brief helper macros to assign the value to a BOOL, UINT, static string and
00727  * dynamic string
00728  */
00729 #define  CV_BOOL(__x, __dst)  CV_F(__x, (__dst) = ast_true(__val) )
00730 #define CV_UINT(__x, __dst)   CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
00731 #define CV_STR(__x, __dst) CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
00732 #define CV_DSTR(__x, __dst)   CV_F(__x, ast_free(__dst); __dst = ast_strdup(__val))
00733 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
00734 
00735 /*! \brief Check if require type is an integer type */
00736 AST_INLINE_API(
00737 int ast_rq_is_int(require_type type),
00738 {
00739    switch (type) {
00740    case RQ_INTEGER1:
00741    case RQ_UINTEGER1:
00742    case RQ_INTEGER2:
00743    case RQ_UINTEGER2:
00744    case RQ_INTEGER3:
00745    case RQ_UINTEGER3:
00746    case RQ_INTEGER4:
00747    case RQ_UINTEGER4:
00748    case RQ_INTEGER8:
00749    case RQ_UINTEGER8:
00750       return 1;
00751    default:
00752       return 0;
00753    }
00754 }
00755 )
00756 
00757 /*!
00758  * \brief Remove standard encoding from realtime values, which ensures
00759  * that a semicolon embedded within a single value is not treated upon
00760  * retrieval as multiple values.
00761  * \param chunk Data to be decoded
00762  * \return The decoded data, in the original buffer
00763  * \since 1.8
00764  * \warn This function modifies the original buffer
00765  */
00766 char *ast_realtime_decode_chunk(char *chunk);
00767 
00768 /*!
00769  * \brief Encodes a chunk of data for realtime
00770  * \param dest Destination buffer
00771  * \param maxlen Length passed through to ast_str_* functions
00772  * \param chunk Source data to be encoded
00773  * \return Buffer within dest
00774  * \since 1.8
00775  */
00776 char *ast_realtime_encode_chunk(struct ast_str **dest, ssize_t maxlen, const char *chunk);
00777 
00778 #if defined(__cplusplus) || defined(c_plusplus)
00779 }
00780 #endif
00781 
00782 #endif /* _ASTERISK_CONFIG_H */

Generated on Sat Mar 10 01:54:15 2012 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7