include/asterisk/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 /*! Flags for ast_config_text_file_save2()
00051  */
00052 enum config_save_flags {
00053    CONFIG_SAVE_FLAG_NONE = (0),
00054    /*! Insure a context doesn't effectively change if a template changes (pre 13.2 behavior) */
00055    CONFIG_SAVE_FLAG_PRESERVE_EFFECTIVE_CONTEXT = (1 << 0),
00056 };
00057 
00058 #define  CONFIG_STATUS_FILEMISSING  (void *)0
00059 #define  CONFIG_STATUS_FILEUNCHANGED   (void *)-1
00060 #define  CONFIG_STATUS_FILEINVALID  (void *)-2
00061 
00062 /*!
00063  * \brief Types used in ast_realtime_require_field
00064  */
00065 typedef enum {
00066    RQ_INTEGER1,
00067    RQ_UINTEGER1,
00068    RQ_INTEGER2,
00069    RQ_UINTEGER2,
00070    RQ_INTEGER3,
00071    RQ_UINTEGER3,
00072    RQ_INTEGER4,
00073    RQ_UINTEGER4,
00074    RQ_INTEGER8,
00075    RQ_UINTEGER8,
00076    RQ_CHAR,
00077    RQ_FLOAT,
00078    RQ_DATE,
00079    RQ_DATETIME,
00080 } require_type;
00081 
00082 /*! \brief Structure for variables, used for configurations and for channel variables */
00083 struct ast_variable {
00084    /*! Variable name.  Stored in stuff[] at struct end. */
00085    const char *name;
00086    /*! Variable value.  Stored in stuff[] at struct end. */
00087    const char *value;
00088 
00089    /*! Next node in the list. */
00090    struct ast_variable *next;
00091 
00092    /*! Filename where variable found.  Stored in stuff[] at struct end. */
00093    const char *file;
00094 
00095    int lineno;
00096    int object;    /*!< 0 for variable, 1 for object */
00097    int blanklines;      /*!< Number of blanklines following entry */
00098    int inherited;    /*!< 1 for inherited from template or other base */
00099    struct ast_comment *precomments;
00100    struct ast_comment *sameline;
00101    struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
00102    /*!
00103     * \brief Contents of file, name, and value in that order stuffed here.
00104     * \note File must be stuffed before name because of ast_include_rename().
00105     */
00106    char stuff[0];
00107 };
00108 
00109 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);
00110 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, const struct ast_variable *fields);
00111 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, const struct ast_variable *fields);
00112 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields);
00113 typedef int realtime_update2(const char *database, const char *table, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields);
00114 typedef int realtime_store(const char *database, const char *table, const struct ast_variable *fields);
00115 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields);
00116 
00117 /*!
00118  * \brief Function pointer called to ensure database schema is properly configured for realtime use
00119  * \since 1.6.1
00120  */
00121 typedef int realtime_require(const char *database, const char *table, va_list ap);
00122 
00123 /*!
00124  * \brief Function pointer called to clear the database cache and free resources used for such
00125  * \since 1.6.1
00126  */
00127 typedef int realtime_unload(const char *database, const char *table);
00128 
00129 /*! \brief Configuration engine structure, used to define realtime drivers */
00130 struct ast_config_engine {
00131    char *name;
00132    config_load_func *load_func;
00133    realtime_var_get *realtime_func;
00134    realtime_multi_get *realtime_multi_func;
00135    realtime_update *update_func;
00136    realtime_update2 *update2_func;
00137    realtime_store *store_func;
00138    realtime_destroy *destroy_func;
00139    realtime_require *require_func;
00140    realtime_unload *unload_func;
00141    struct ast_config_engine *next;
00142 };
00143 
00144 /*!
00145  * \brief Load a config file
00146  *
00147  * \param filename path of file to open.  If no preceding '/' character,
00148  * path is considered relative to AST_CONFIG_DIR
00149  * \param who_asked The module which is making this request.
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 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
00162 
00163 /*!
00164  * \brief Load a config file
00165  *
00166  * \param filename path of file to open.  If no preceding '/' character,
00167  * path is considered relative to AST_CONFIG_DIR
00168  * \param flags Optional flags:
00169  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
00170  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
00171  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
00172  *
00173  * \details
00174  * Create a config structure from a given configuration file.
00175  *
00176  * \return an ast_config data structure on success
00177  * \retval NULL on error
00178  */
00179 #define ast_config_load(filename, flags)  ast_config_load2(filename, AST_MODULE, flags)
00180 
00181 /*!
00182  * \brief Destroys a config
00183  *
00184  * \param config pointer to config data structure
00185  *
00186  * \details
00187  * Free memory associated with a given config
00188  */
00189 void ast_config_destroy(struct ast_config *config);
00190 
00191 /*!
00192  * \brief returns the root ast_variable of a config
00193  *
00194  * \param config pointer to an ast_config data structure
00195  * \param cat name of the category for which you want the root
00196  *
00197  * \return the category specified
00198  */
00199 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
00200 
00201 /*!
00202  * \brief Sorts categories in a config in the order of a numerical value contained within them.
00203  *
00204  * \param config The config structure you wish to sort
00205  * \param comparator variable Which numerical value you wish to sort by
00206  * \param descending If true, we sort highest to lowest instead of lowest to highest
00207  *
00208  * \details
00209  * This function will assume a value of 0 for any non-numerical strings and NULL fields.
00210  */
00211 void ast_config_sort_categories(struct ast_config *config, int descending,
00212                         int (*comparator)(struct ast_category *p, struct ast_category *q));
00213 
00214 /*!
00215  * \brief Browse categories with filters
00216  *
00217  * \param config Which config structure you wish to "browse"
00218  * \param category_name An optional category name.
00219  * Pass NULL to not restrict by category name.
00220  * \param prev A pointer to the starting category structure.
00221  * Pass NULL to start at the beginning.
00222  * \param filter An optional comma-separated list of <name_regex>=<value_regex>
00223  * pairs.  Only categories with matching variables will be returned.
00224  * The special name 'TEMPLATES' can be used with the special values
00225  * 'include' or 'restrict' to include templates in the result or
00226  * restrict the result to only templates.
00227  *
00228  * \retval a category on success
00229  * \retval NULL on failure/no-more-categories
00230  */
00231 struct ast_category *ast_category_browse_filtered(struct ast_config *config,
00232    const char *category_name, struct ast_category *prev, const char *filter);
00233 
00234 /*!
00235  * \brief Browse categories
00236  *
00237  * \param config Which config structure you wish to "browse"
00238  * \param prev_name A pointer to a previous category name.
00239  *
00240  * \details
00241  * This function is kind of non-intuitive in it's use.
00242  * To begin, one passes NULL as the second argument.
00243  * It will return a pointer to the string of the first category in the file.
00244  * From here on after, one must then pass the previous usage's return value
00245  * as the second pointer, and it will return a pointer to the category name
00246  * afterwards.
00247  *
00248  * \retval a category name on success
00249  * \retval NULL on failure/no-more-categories
00250  *
00251  * \note ast_category_browse maintains internal state.  Therefore is not thread
00252  * safe, cannot be called recursively, and it is not safe to add or remove
00253  * categories while browsing.
00254  * ast_category_browse_filtered does not have these restrictions.
00255  */
00256 char *ast_category_browse(struct ast_config *config, const char *prev_name);
00257 
00258 /*!
00259  * \brief Browse variables
00260  * \param config Which config structure you wish to "browse"
00261  * \param category_name Which category to "browse"
00262  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
00263  * pairs.  Only categories with matching variables will be browsed.
00264  * The special name 'TEMPLATES' can be used with the special values
00265  * 'include' or 'restrict' to include templates in the result or
00266  * restrict the result to only templates.
00267  *
00268  * \details
00269  * Somewhat similar in intent as the ast_category_browse.
00270  * List variables of config file category
00271  *
00272  * \retval ast_variable list on success
00273  * \retval NULL on failure
00274  */
00275 struct ast_variable *ast_variable_browse_filtered(const struct ast_config *config,
00276    const char *category_name, const char *filter);
00277 struct ast_variable *ast_variable_browse(const struct ast_config *config,
00278    const char *category_name);
00279 
00280 /*!
00281  * \brief given a pointer to a category, return the root variable.
00282  *
00283  * \details
00284  * This is equivalent to ast_variable_browse(), but more efficient if we
00285  * already have the struct ast_category * (e.g. from ast_category_get())
00286  */
00287 struct ast_variable *ast_category_first(struct ast_category *cat);
00288 
00289 /*!
00290  * \brief Gets a variable by context and variable names
00291  *
00292  * \param config which (opened) config to use
00293  * \param category category under which the variable lies
00294  * \param variable which variable you wish to get the data for
00295  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
00296  * pairs.  Only categories with matching variables will be searched.
00297  * The special name 'TEMPLATES' can be used with the special values
00298  * 'include' or 'restrict' to include templates in the result or
00299  * restrict the result to only templates.
00300  *
00301  * \retval The variable value on success
00302  * \retval NULL if unable to find it.
00303  */
00304 const char *ast_variable_retrieve_filtered(struct ast_config *config,
00305    const char *category, const char *variable, const char *filter);
00306 const char *ast_variable_retrieve(struct ast_config *config,
00307    const char *category, const char *variable);
00308 
00309 /*!
00310  * \brief Gets a variable from a specific category structure
00311  *
00312  * \param category category structure under which the variable lies
00313  * \param variable which variable you wish to get the data for
00314  *
00315  * \details
00316  * Goes through a given category and searches for the given variable
00317  *
00318  * \retval The variable value on success
00319  * \retval NULL if unable to find it.
00320  */
00321 const char *ast_variable_find(const struct ast_category *category, const char *variable);
00322 
00323 /*!
00324  * \brief Gets a variable from a variable list
00325  *
00326  * \param list variable list to search
00327  * \param variable which variable you wish to get the data for
00328  *
00329  * \details
00330  * Goes through a given variable list and searches for the given variable
00331  *
00332  * \retval The variable value on success
00333  * \retval NULL if unable to find it.
00334  */
00335 const char *ast_variable_find_in_list(const struct ast_variable *list, const char *variable);
00336 
00337 /*!
00338  * \brief Retrieve a category if it exists
00339  *
00340  * \param config which config to use
00341  * \param category_name name of the category you're looking for
00342  * \param filter If a config contains more than 1 category with the same name,
00343  * you can specify a filter to narrow the search.  The filter is a comma-separated
00344  * list of <name_regex>=<value_regex> pairs.  Only a category with matching
00345  * variables will be returned. The special name 'TEMPLATES' can be used with the
00346  * special values 'include' or 'restrict' to include templates in the result or
00347  * restrict the result to only templates.
00348  *
00349  * \details
00350  * This will search through the categories within a given config file for a match.
00351  *
00352  * \retval pointer to category if found
00353  * \retval NULL if not.
00354  */
00355 struct ast_category *ast_category_get(const struct ast_config *config,
00356    const char *category_name, const char *filter);
00357 
00358 /*!
00359  * \brief Return the name of the category
00360  *
00361  * \param category category structure
00362  *
00363  * \retval pointer to category name if found
00364  * \retval NULL if not.
00365  */
00366 const char *ast_category_get_name(const struct ast_category *category);
00367 
00368 /*!
00369  * \brief Check if category is a template
00370  *
00371  * \param category category structure
00372  *
00373  * \retval 1 if a template.
00374  * \retval 0 if not.
00375  */
00376 int ast_category_is_template(const struct ast_category *category);
00377 
00378 /*!
00379  * \brief Return the template names this category inherits from
00380  *
00381  * \param category category structure
00382  *
00383  * \return an ast_str (which must be freed after use) with a comma
00384  * separated list of templates names or NULL if there were no templates.
00385  */
00386 struct ast_str *ast_category_get_templates(const struct ast_category *category);
00387 
00388 /*!
00389  * \brief Check for category duplicates
00390  *
00391  * \param config which config to use
00392  * \param category_name name of the category you're looking for
00393  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
00394  * pairs.  Only categories with matching variables will be returned.
00395  * The special name 'TEMPLATES' can be used with the special values
00396  * 'include' or 'restrict' to include templates in the result or
00397  * restrict the result to only templates.
00398  *
00399  * \details
00400  * This will search through the categories within a given config file for a match.
00401  *
00402  * \return non-zero if found
00403  */
00404 int ast_category_exist(const struct ast_config *config, const char *category_name,
00405    const char *filter);
00406 
00407 /*!
00408  * \brief Retrieve realtime configuration
00409  *
00410  * \param family which family/config to lookup
00411  *
00412  * \details
00413  * This will use builtin configuration backends to look up a particular
00414  * entity in realtime and return a variable list of its parameters.
00415  *
00416  * \note
00417  * Unlike the variables in ast_config, the resulting list of variables
00418  * MUST be freed with ast_variables_destroy() as there is no container.
00419  *
00420  * \note
00421  * The difference between these two calls is that ast_load_realtime excludes
00422  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
00423  *
00424  * \note
00425  * You should use the constant SENTINEL to terminate arguments, in
00426  * order to preserve cross-platform compatibility.
00427  */
00428 struct ast_variable *ast_load_realtime_fields(const char *family, const struct ast_variable *fields);
00429 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
00430 struct ast_variable *ast_load_realtime_all_fields(const char *family, const struct ast_variable *fields);
00431 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
00432 
00433 /*!
00434  * \brief Release any resources cached for a realtime family
00435  * \since 1.6.1
00436  *
00437  * \param family which family/config to destroy
00438  *
00439  * \details
00440  * Various backends may cache attributes about a realtime data storage
00441  * facility; on reload, a front end resource may request to purge that cache.
00442  *
00443  * \retval 0 If any cache was purged
00444  * \retval -1 If no cache was found
00445  */
00446 int ast_unload_realtime(const char *family);
00447 
00448 /*!
00449  * \brief Inform realtime what fields that may be stored
00450  * \since 1.6.1
00451  *
00452  * \param family which family/config is referenced
00453  *
00454  * \details
00455  * This will inform builtin configuration backends that particular fields
00456  * may be updated during the use of that configuration section.  This is
00457  * mainly to be used during startup routines, to ensure that various fields
00458  * exist in the backend.  The backends may take various actions, such as
00459  * creating new fields in the data store or warning the administrator that
00460  * new fields may need to be created, in order to ensure proper function.
00461  *
00462  * The arguments are specified in groups of 3:  column name, column type,
00463  * and column size.  The column types are specified as integer constants,
00464  * defined by the enum require_type.  Note that the size is specified as
00465  * the number of equivalent character fields that a field may take up, even
00466  * if a field is otherwise specified as an integer type.  This is due to
00467  * the fact that some fields have historically been specified as character
00468  * types, even if they contained integer values.
00469  *
00470  * A family should always specify its fields to the minimum necessary
00471  * requirements to fulfill all possible values (within reason; for example,
00472  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
00473  * Even though values above 32767 seconds are possible, they are unlikely
00474  * to be useful, and we should not complain about that size).
00475  *
00476  * \retval 0 Required fields met specified standards
00477  * \retval -1 One or more fields was missing or insufficient
00478  *
00479  * \note You should use the constant SENTINEL to terminate arguments, in
00480  * order to preserve cross-platform compatibility.
00481  */
00482 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
00483 
00484 /*!
00485  * \brief Retrieve realtime configuration
00486  *
00487  * \param family which family/config to lookup
00488  * \param fields list of fields
00489  *
00490  * \details
00491  * This will use builtin configuration backends to look up a particular
00492  * entity in realtime and return a variable list of its parameters. Unlike
00493  * the ast_load_realtime, this function can return more than one entry and
00494  * is thus stored inside a traditional ast_config structure rather than
00495  * just returning a linked list of variables.
00496  *
00497  * \return An ast_config with one or more results
00498  * \retval NULL Error or no results returned
00499  */
00500 struct ast_config *ast_load_realtime_multientry_fields(const char *family, const struct ast_variable *fields);
00501 
00502 /*!
00503  * \brief Retrieve realtime configuration
00504  *
00505  * \param family which family/config to lookup
00506  *
00507  * \details
00508  * This will use builtin configuration backends to look up a particular
00509  * entity in realtime and return a variable list of its parameters. Unlike
00510  * the ast_load_realtime, this function can return more than one entry and
00511  * is thus stored inside a traditional ast_config structure rather than
00512  * just returning a linked list of variables.
00513  *
00514  * \return An ast_config with one or more results
00515  * \retval NULL Error or no results returned
00516  *
00517  * \note You should use the constant SENTINEL to terminate arguments, in
00518  * order to preserve cross-platform compatibility.
00519  */
00520 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
00521 
00522 /*!
00523  * \brief Update realtime configuration
00524  *
00525  * \param family which family/config to be updated
00526  * \param keyfield which field to use as the key
00527  * \param lookup which value to look for in the key field to match the entry.
00528  * \param fields fields to update
00529  *
00530  * \details
00531  * This function is used to update a parameter in realtime configuration space.
00532  *
00533  * \return Number of rows affected, or -1 on error.
00534  */
00535 int ast_update_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
00536 
00537 /*!
00538  * \brief Update realtime configuration
00539  *
00540  * \param family which family/config to be updated
00541  * \param keyfield which field to use as the key
00542  * \param lookup which value to look for in the key field to match the entry.
00543  *
00544  * \details
00545  * This function is used to update a parameter in realtime configuration space.
00546  *
00547  * \return Number of rows affected, or -1 on error.
00548  *
00549  * \note You should use the constant SENTINEL to terminate arguments, in
00550  * order to preserve cross-platform compatibility.
00551  */
00552 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
00553 
00554 /*!
00555  * \brief Update realtime configuration
00556  *
00557  * \param family which family/config to be updated
00558  * \param lookup_fields fields used to look up entries
00559  * \param update_fields fields to update
00560  *
00561  * \details
00562  * This function is used to update a parameter in realtime configuration space.
00563  * It includes the ability to lookup a row based upon multiple key criteria.
00564  * As a result, this function includes two sentinel values, one to terminate
00565  * lookup values and the other to terminate the listing of fields to update.
00566  *
00567  * \return Number of rows affected, or -1 on error.
00568  */
00569 int ast_update2_realtime_fields(const char *family, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields);
00570 
00571 /*!
00572  * \brief Update realtime configuration
00573  *
00574  * \param family which family/config to be updated
00575  *
00576  * \details
00577  * This function is used to update a parameter in realtime configuration space.
00578  * It includes the ability to lookup a row based upon multiple key criteria.
00579  * As a result, this function includes two sentinel values, one to terminate
00580  * lookup values and the other to terminate the listing of fields to update.
00581  *
00582  * \return Number of rows affected, or -1 on error.
00583  *
00584  * \note You should use the constant SENTINEL to terminate arguments, in
00585  * order to preserve cross-platform compatibility.
00586  */
00587 int ast_update2_realtime(const char *family, ...) attribute_sentinel;
00588 
00589 /*!
00590  * \brief Create realtime configuration
00591  *
00592  * \param family which family/config to be created
00593  * \param fields fields themselves
00594  *
00595  * \details
00596  * This function is used to create a parameter in realtime configuration space.
00597  *
00598  * \return Number of rows affected, or -1 on error.
00599  *
00600  * \note
00601  * On the MySQL engine only, for reasons of backwards compatibility, the return
00602  * value is the insert ID.  This value is nonportable and may be changed in a
00603  * future version to match the other engines.
00604  */
00605 int ast_store_realtime_fields(const char *family, const struct ast_variable *fields);
00606 
00607 /*!
00608  * \brief Create realtime configuration
00609  *
00610  * \param family which family/config to be created
00611  *
00612  * \details
00613  * This function is used to create a parameter in realtime configuration space.
00614  *
00615  * \return Number of rows affected, or -1 on error.
00616  *
00617  * \note
00618  * On the MySQL engine only, for reasons of backwards compatibility, the return
00619  * value is the insert ID.  This value is nonportable and may be changed in a
00620  * future version to match the other engines.
00621  *
00622  * \note You should use the constant SENTINEL to terminate arguments, in
00623  * order to preserve cross-platform compatibility.
00624  */
00625 int ast_store_realtime(const char *family, ...) attribute_sentinel;
00626 
00627 /*!
00628  * \brief Destroy realtime configuration
00629  *
00630  * \param family which family/config to be destroyed
00631  * \param keyfield which field to use as the key
00632  * \param lookup which value to look for in the key field to match the entry.
00633  * \param fields fields themselves
00634  *
00635  * \details
00636  * This function is used to destroy an entry in realtime configuration space.
00637  * Additional params are used as keys.
00638  *
00639  * \return Number of rows affected, or -1 on error.
00640  */
00641 int ast_destroy_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
00642 
00643 /*!
00644  * \brief Destroy realtime configuration
00645  *
00646  * \param family which family/config to be destroyed
00647  * \param keyfield which field to use as the key
00648  * \param lookup which value to look for in the key field to match the entry.
00649  *
00650  * \details
00651  * This function is used to destroy an entry in realtime configuration space.
00652  * Additional params are used as keys.
00653  *
00654  * \return Number of rows affected, or -1 on error.
00655  *
00656  * \note You should use the constant SENTINEL to terminate arguments, in
00657  * order to preserve cross-platform compatibility.
00658  */
00659 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
00660 
00661 /*!
00662  * \brief Check if realtime engine is configured for family
00663  * \param family which family/config to be checked
00664  * \return 1 if family is configured in realtime and engine exists
00665  */
00666 int ast_check_realtime(const char *family);
00667 
00668 /*! \brief Check if there's any realtime engines loaded */
00669 int ast_realtime_enabled(void);
00670 
00671 /*!
00672  * \brief Duplicate variable list
00673  * \param var the linked list of variables to clone
00674  * \return A duplicated list which you'll need to free with
00675  * ast_variables_destroy or NULL when out of memory.
00676  *
00677  * \note Do not depend on this to copy more than just name, value and filename
00678  * (the arguments to ast_variables_new).
00679  */
00680 struct ast_variable *ast_variables_dup(struct ast_variable *var);
00681 
00682 /*!
00683  * \brief Reverse a variable list
00684  * \param var the linked list of variables to reverse
00685  * \return The head of the reversed variable list
00686  *
00687  * \note The variable list var is not preserved in this function and should
00688  * not be used after reversing it.
00689  */
00690 struct ast_variable *ast_variables_reverse(struct ast_variable *var);
00691 
00692 /*!
00693  * \brief Free variable list
00694  * \param var the linked list of variables to free
00695  *
00696  * \details
00697  * This function frees a list of variables.
00698  */
00699 void ast_variables_destroy(struct ast_variable *var);
00700 
00701 /*!
00702  * \brief Register config engine
00703  * \retval 1 Always
00704  */
00705 int ast_config_engine_register(struct ast_config_engine *newconfig);
00706 
00707 /*!
00708  * \brief Deregister config engine
00709  * \retval 0 Always
00710  */
00711 int ast_config_engine_deregister(struct ast_config_engine *del);
00712 
00713 /*!
00714  * \brief Determine if a mapping exists for a given family
00715  *
00716  * \param family which family you are looking to see if a mapping exists for
00717  * \retval 1 if it is mapped
00718  * \retval 0 if it is not
00719  */
00720 int ast_realtime_is_mapping_defined(const char *family);
00721 
00722 #ifdef TEST_FRAMEWORK
00723 /*!
00724  * \brief Add an explicit mapping for a family
00725  *
00726  * \param name Family name
00727  * \param driver Driver to use
00728  * \param database Database to access
00729  * \param table Table to use
00730  * \param priority Priority of this mapping
00731  */
00732 int ast_realtime_append_mapping(const char *name, const char *driver, const char *database, const char *table, int priority);
00733 #endif
00734 
00735 /*!
00736  * \brief Exposed initialization method for core process
00737  *
00738  * \details
00739  * This method is intended for use only with the core initialization and is
00740  * not designed to be called from any user applications.
00741  */
00742 int register_config_cli(void);
00743 
00744 /*!
00745  * \brief Exposed re-initialization method for core process
00746  *
00747  * \details
00748  * This method is intended for use only with the core re-initialization and is
00749  * not designed to be called from any user applications.
00750  */
00751 int read_config_maps(void);
00752 
00753 /*! \brief Create a new base configuration structure */
00754 struct ast_config *ast_config_new(void);
00755 
00756 /*!
00757  * \brief Retrieve the current category name being built.
00758  *
00759  * \details
00760  * API for backend configuration engines while building a configuration set.
00761  */
00762 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
00763 
00764 /*!
00765  * \brief Set the category within the configuration as being current.
00766  *
00767  * \details
00768  * API for backend configuration engines while building a configuration set.
00769  */
00770 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
00771 
00772 /*!
00773  * \brief Retrieve a configuration variable within the configuration set.
00774  *
00775  * \details
00776  * Retrieves the named variable \p var within category \p cat of configuration
00777  * set \p cfg.  If not found, attempts to retrieve the named variable \p var
00778  * from within category \em general.
00779  *
00780  * \return Value of \p var, or NULL if not found.
00781  */
00782 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
00783 
00784 /*!
00785  * \brief Create a category
00786  *
00787  * \param name name of new category
00788  * \param in_file filename which contained the new config
00789  * \param lineno line number
00790  */
00791 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
00792 
00793 /*!
00794  * \brief Create a category making it a template
00795  *
00796  * \param name name of new template
00797  * \param in_file filename which contained the new config
00798  * \param lineno line number
00799  */
00800 struct ast_category *ast_category_new_template(const char *name, const char *in_file, int lineno);
00801 
00802 /*!
00803  * \brief Inserts new category
00804  * 
00805  * \param config which config to use
00806  * \param cat newly created category to insert
00807  * \param match which category to insert above
00808  *
00809  * \details
00810  * This function is used to insert a new category above another category
00811  * matching the match parameter.
00812  *
00813  * \retval 0 if succeeded
00814  * \retval -1 if the specified match category wasn't found
00815  */
00816 int ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
00817 
00818 /*!
00819  * \brief Delete a category
00820  *
00821  * \param config which config to use
00822  * \param category category to delete
00823  *
00824  * \return the category after the deleted one which could be NULL.
00825  *
00826  * \note It is not safe to call ast_category_delete while browsing with
00827  * ast_category_browse.  It is safe with ast_category_browse_filtered.
00828  */
00829 struct ast_category *ast_category_delete(struct ast_config *cfg, struct ast_category *category);
00830 
00831 /*!
00832  * \brief Appends a category to a config
00833  *
00834  * \param config which config to use
00835  * \param cat category to insert
00836  */
00837 void ast_category_append(struct ast_config *config, struct ast_category *cat);
00838 
00839 /*!
00840  * \brief Applies base (template) to category.
00841  *
00842  * \param existing existing category
00843  * \param base base category
00844  *
00845  * \details
00846  * This function is used to apply a base (template) to an existing category
00847  *
00848  * \retval 0 if succeeded
00849  * \retval -1 if the memory allocation failed
00850  */
00851 int ast_category_inherit(struct ast_category *existing, const struct ast_category *base);
00852 
00853 /*!
00854  * \brief Removes and destroys all variables in a category
00855  *
00856  * \param category category to empty
00857  *
00858  * \retval 0 if succeeded
00859  * \retval -1 if categopry is NULL
00860  */
00861 int ast_category_empty(struct ast_category *category);
00862 
00863 void ast_category_destroy(struct ast_category *cat);
00864 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
00865 void ast_category_rename(struct ast_category *cat, const char *name);
00866 
00867 #ifdef MALLOC_DEBUG
00868 struct ast_variable *_ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno);
00869 #define ast_variable_new(name, value, filename) _ast_variable_new(name, value, filename, __FILE__, __PRETTY_FUNCTION__, __LINE__)
00870 #else
00871 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
00872 #endif
00873 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);
00874 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
00875 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
00876 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
00877 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
00878 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
00879 
00880 /*!
00881  * \brief Performs an in-place sort on the variable list by ascending name
00882  *
00883  * \param head The variable list head
00884  *
00885  * \return The new list head
00886  */
00887 struct ast_variable *ast_variable_list_sort(struct ast_variable *head);
00888 
00889 /*!
00890  * \brief Appends a variable list to the end of another list
00891  *
00892  * \param head A pointer to an ast_variable * of the existing variable list head. May NOT be NULL
00893  * but the content may be to initialize a new list.  If so, upon return, this parameter will be updated
00894  * with a pointer to the new list head.
00895  * \param search_hint The place in the current list to start searching for the end of the list.
00896  * Might help performance on longer lists.  If NULL, it defaults to head.
00897  * \param new_var The head of the new variable list to be appended
00898  *
00899  * \return The tail of the resulting list.
00900  *
00901  * \note If the existing *head is NULL, it will be updated to new_var.  This allows you to call
00902  * ast_variable_list_append in a loop or callback without initializing the list first.
00903  */
00904 struct ast_variable *ast_variable_list_append_hint(struct ast_variable **head, struct ast_variable *search_hint,
00905    struct ast_variable *new_var);
00906 #define ast_variable_list_append(head, new_var) ast_variable_list_append_hint(head, NULL, new_var)
00907 
00908 /*!
00909  * \brief Update variable value within a config
00910  *
00911  * \param category Category element within the config
00912  * \param variable Name of the variable to change
00913  * \param value New value of the variable
00914  * \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
00915  * \param object Boolean of whether to make the new variable an object
00916  *
00917  * \return 0 on success or -1 on failure.
00918  */
00919 int ast_variable_update(struct ast_category *category, const char *variable,
00920                   const char *value, const char *match, unsigned int object);
00921 
00922 /*!
00923  * \brief Save a config text file
00924  * \since 13.2.0
00925  *
00926  * \param filename Filename
00927  * \param cfg ast_config
00928  * \param generator generator
00929  * \param flags List of config_save_flags
00930  *
00931  * \return 0 on success or -1 on failure.
00932  */
00933 int ast_config_text_file_save2(const char *filename, const struct ast_config *cfg, const char *generator, uint32_t flags);
00934 
00935 /*!
00936  * \brief Save a config text file preserving the pre 13.2 behavior
00937  *
00938  * \param filename Filename
00939  * \param cfg ast_config
00940  * \param generator generator
00941  *
00942  * \return 0 on success or -1 on failure.
00943  */
00944 int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
00945 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator) __attribute__((deprecated));
00946 
00947 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);
00948 /*!
00949  * \brief
00950  * Copies the contents of one ast_config into another
00951  *
00952  * \note
00953  * This creates a config on the heap. The caller of this must
00954  * be prepared to free the memory returned.
00955  *
00956  * \param orig the config to copy
00957  * \return The new config on success, NULL on failure.
00958  */
00959 struct ast_config *ast_config_copy(const struct ast_config *orig);
00960 
00961 /*!
00962  * \brief
00963  * Flags that affect the behaviour of config hooks.
00964  */
00965 enum config_hook_flags {
00966    butt,
00967 };
00968 
00969 /*
00970  * \brief Callback when configuration is updated
00971  *
00972  * \param cfg A copy of the configuration that is being changed.
00973  *            This MUST be freed by the callback before returning.
00974  */
00975 typedef int (*config_hook_cb)(struct ast_config *cfg);
00976 
00977 /*!
00978  * \brief
00979  * Register a config hook for a particular file and module
00980  *
00981  * \param name The name of the hook you are registering.
00982  * \param filename The file whose config you wish to hook into.
00983  * \param module The module that is reloading the config. This
00984  *               can be useful if multiple modules may possibly
00985  *               reload the same file, but you are only interested
00986  *               when a specific module reloads the file
00987  * \param flags Flags that affect the way hooks work.
00988  * \param hook The callback to be called when config is loaded.
00989  * return 0 Success
00990  * return -1 Unsuccess, also known as UTTER AND COMPLETE FAILURE
00991  */
00992 int ast_config_hook_register(const char *name,
00993       const char *filename,
00994       const char *module,
00995       enum config_hook_flags flags,
00996       config_hook_cb hook);
00997 
00998 /*!
00999  * \brief
01000  * Unregister a config hook
01001  *
01002  * \param name The name of the hook to unregister
01003  */
01004 void ast_config_hook_unregister(const char *name);
01005 
01006 /*!
01007  * \brief Support code to parse config file arguments
01008  *
01009  * \details
01010  * The function ast_parse_arg() provides a generic interface to parse
01011  * strings (e.g. numbers, network addresses and so on) in a flexible
01012  * way, e.g. by doing proper error and bound checks, provide default
01013  * values, and so on.
01014  * The function (described later) takes a string as an argument,
01015  * a set of flags to specify the result format and checks to perform,
01016  * a pointer to the result, and optionally some additional arguments.
01017  *
01018  * \return It returns 0 on success, != 0 otherwise.
01019  */
01020 enum ast_parse_flags {
01021    /* low 4 bits of flags are used for the operand type */
01022    PARSE_TYPE  =  0x000f,
01023    /* numeric types, with optional default value and bound checks.
01024     * Additional arguments are passed by value.
01025     */
01026    PARSE_INT32 =  0x0001,
01027    PARSE_UINT32   =  0x0002,
01028    PARSE_DOUBLE   =  0x0003,
01029 #if 0 /* not supported yet */
01030    PARSE_INT16 =  0x0004,
01031    PARSE_UINT16   =  0x0005,
01032 #endif
01033 
01034    /* Returns a struct ast_sockaddr, with optional default value
01035     * (passed by reference) and port handling (accept, ignore,
01036     * require, forbid). The format is 'ipaddress[:port]'. IPv6 address
01037     * literals need square brackets around them if a port is specified.
01038     */
01039    PARSE_ADDR  =  0x000e,
01040 
01041    /* Returns a struct sockaddr_in, with optional default value
01042     * (passed by reference) and port handling (accept, ignore,
01043     * require, forbid). The format is 'host.name[:port]'
01044     */
01045    PARSE_INADDR   =  0x000f,
01046 
01047    /* Other data types can be added as needed */
01048 
01049    /* If PARSE_DEFAULT is set, next argument is a default value
01050     * which is returned in case of error. The argument is passed
01051     * by value in case of numeric types, by reference in other cases.
01052     */
01053    PARSE_DEFAULT  =  0x0010,  /* assign default on error */
01054 
01055    /* Request a range check, applicable to numbers. Two additional
01056     * arguments are passed by value, specifying the low-high end of
01057     * the range (inclusive). An error is returned if the value
01058     * is outside or inside the range, respectively.
01059     */
01060    PARSE_IN_RANGE =       0x0020, /* accept values inside a range */
01061    PARSE_OUT_RANGE =      0x0040, /* accept values outside a range */
01062    PARSE_RANGE_DEFAULTS = 0x0080, /* default to range min/max on range error */
01063 
01064    /* Port handling, for ast_sockaddr. accept/ignore/require/forbid
01065     * port number after the hostname or address.
01066     */
01067    PARSE_PORT_MASK = 0x0300, /* 0x000: accept port if present */
01068    PARSE_PORT_IGNORE =  0x0100, /* 0x100: ignore port if present */
01069    PARSE_PORT_REQUIRE = 0x0200, /* 0x200: require port number */
01070    PARSE_PORT_FORBID =  0x0300, /* 0x100: forbid port number */
01071 };
01072 
01073 /*!
01074  * \brief The argument parsing routine.
01075  *
01076  * \param arg the string to parse. It is not modified.
01077  * \param flags combination of ast_parse_flags to specify the
01078  *    return type and additional checks.
01079  * \param result pointer to the result. NULL is valid here, and can
01080  *    be used to perform only the validity checks.
01081  * \param ... extra arguments are required according to flags.
01082  *
01083  * \retval 0 in case of success, != 0 otherwise.
01084  * \retval result returns the parsed value in case of success,
01085  * the default value in case of error, or it is left unchanged
01086  * in case of error and no default specified. Note that in certain
01087  * cases (e.g. sockaddr_in, with multi-field return values) some
01088  * of the fields in result may be changed even if an error occurs.
01089  *
01090  * \details
01091  * Examples of use:
01092  *     ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE, &a, -1000, 1000);
01093  * returns 0, a = 223
01094  *     ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT, &a, 9999, 10, 100);
01095  * returns 1, a = 9999
01096  *     ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
01097  * returns 1, b unchanged
01098  *    ast_parse_arg("12", PARSE_UINT32|PARSE_IN_RANGE|PARSE_RANGE_DEFAULTS, &a, 1, 10);
01099  * returns 1, a = 10
01100  *    ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
01101  * returns 0, sa contains address and port
01102  *    ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
01103  * returns 1 because port is missing, sa contains address
01104  */
01105 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
01106         void *result, ...);
01107 
01108 /*
01109  * Parsing config file options in C is slightly annoying because we cannot use
01110  * string in a switch() statement, yet we need a similar behaviour, with many
01111  * branches and a break on a matching one.
01112  * The following somehow simplifies the job: we create a block using
01113  * the CV_START and CV_END macros, and then within the block we can run
01114  * actions such as "if (condition) { body; break; }"
01115  * Additional macros are present to run simple functions (e.g. ast_copy_string)
01116  * or to pass arguments to ast_parse_arg()
01117  *
01118  * As an example:
01119 
01120    CV_START(v->name, v->value);  // start the block
01121    CV_STR("foo", x_foo);      // static string
01122    CV_DSTR("bar", y_bar);     // malloc'ed string
01123    CV_F("bar", ...);    // call a generic function
01124    CV_END;           // end the block
01125  */
01126 
01127 /*! \brief the macro to open a block for variable parsing */
01128 #define CV_START(__in_var, __in_val)      \
01129    do {              \
01130       const char *__var = __in_var; \
01131       const char *__val = __in_val;
01132 
01133 /*! \brief close a variable parsing block */
01134 #define  CV_END         } while (0)
01135 
01136 /*! \brief call a generic function if the name matches. */
01137 #define  CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
01138 
01139 /*!
01140  * \brief helper macros to assign the value to a BOOL, UINT, static string and
01141  * dynamic string
01142  */
01143 #define  CV_BOOL(__x, __dst)  CV_F(__x, (__dst) = ast_true(__val) )
01144 #define CV_UINT(__x, __dst)   CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
01145 #define CV_STR(__x, __dst) CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
01146 #define CV_DSTR(__x, __dst)   CV_F(__x, ast_free(__dst); __dst = ast_strdup(__val))
01147 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
01148 
01149 /*! \brief Check if require type is an integer type */
01150 AST_INLINE_API(
01151 int ast_rq_is_int(require_type type),
01152 {
01153    switch (type) {
01154    case RQ_INTEGER1:
01155    case RQ_UINTEGER1:
01156    case RQ_INTEGER2:
01157    case RQ_UINTEGER2:
01158    case RQ_INTEGER3:
01159    case RQ_UINTEGER3:
01160    case RQ_INTEGER4:
01161    case RQ_UINTEGER4:
01162    case RQ_INTEGER8:
01163    case RQ_UINTEGER8:
01164       return 1;
01165    default:
01166       return 0;
01167    }
01168 }
01169 )
01170 
01171 /*!
01172  * \brief Remove standard encoding from realtime values, which ensures
01173  * that a semicolon embedded within a single value is not treated upon
01174  * retrieval as multiple values.
01175  * \param chunk Data to be decoded
01176  * \return The decoded data, in the original buffer
01177  * \since 1.8
01178  * \warning This function modifies the original buffer
01179  */
01180 char *ast_realtime_decode_chunk(char *chunk);
01181 
01182 /*!
01183  * \brief Encodes a chunk of data for realtime
01184  * \param dest Destination buffer
01185  * \param maxlen Length passed through to ast_str_* functions
01186  * \param chunk Source data to be encoded
01187  * \return Buffer within dest
01188  * \since 1.8
01189  */
01190 char *ast_realtime_encode_chunk(struct ast_str **dest, ssize_t maxlen, const char *chunk);
01191 
01192 #if defined(__cplusplus) || defined(c_plusplus)
01193 }
01194 #endif
01195 
01196 #endif /* _ASTERISK_CONFIG_H */

Generated on Thu Apr 16 06:27:31 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6