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