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

Generated on Mon Jun 27 16:50:53 2011 for Asterisk - The Open Source Telephony Project by  doxygen 1.4.7