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 */