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