include/asterisk/config.h

   1 /*
   2  * Asterisk -- An open source telephony toolkit.
   3  *
   4  * Copyright (C) 1999 - 2005, Digium, Inc.
   5  *
   6  * Mark Spencer <markster@digium.com>
   7  *
   8  * See http://www.asterisk.org for more information about
   9  * the Asterisk project. Please do not directly contact
  10  * any of the maintainers of this project for assistance;
  11  * the project provides a web site, mailing lists and IRC
  12  * channels for your use.
  13  *
  14  * This program is free software, distributed under the terms of
  15  * the GNU General Public License Version 2. See the LICENSE file
  16  * at the top of the source tree.
  17  */
  18
  19 /*! \file
  20  * \brief Configuration File Parser
  21  */
  22
  23 #ifndef _ASTERISK_CONFIG_H
  24 #define _ASTERISK_CONFIG_H
  25
  26 #if defined(__cplusplus) || defined(c_plusplus)
  27 extern "C" {
  28 #endif
  29
  30 #include <stdarg.h>
  31
  32 struct ast_config;
  33
  34 struct ast_category;
  35
  36 struct ast_variable {
  37         char *name;
  38         char *value;
  39         int lineno;
  40         int object;             /*!< 0 for variable, 1 for object */
  41         int blanklines;         /*!< Number of blanklines following entry */
  42         struct ast_comment *precomments;
  43         struct ast_comment *sameline;
  44         struct ast_variable *next;
  45         char stuff[0];
  46 };
  47
  48 typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config, int withcomments);
  49 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
  50 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
  51 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
  52
  53 struct ast_config_engine {
  54         char *name;
  55         config_load_func *load_func;
  56         realtime_var_get *realtime_func;
  57         realtime_multi_get *realtime_multi_func;
  58         realtime_update *update_func;
  59         struct ast_config_engine *next;
  60 };
  61
  62 /*! \brief Load a config file
  63  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
  64  * Create a config structure from a given configuration file.
  65  *
  66  * Returns NULL on error, or an ast_config data structure on success
  67  */
  68 struct ast_config *ast_config_load(const char *filename);
  69 struct ast_config *ast_config_load_with_comments(const char *filename);
  70
  71 /*! \brief Destroys a config
  72  * \param config pointer to config data structure
  73  * Free memory associated with a given config
  74  *
  75  */
  76 void ast_config_destroy(struct ast_config *config);
  77
  78 /*! \brief returns the root ast_variable of a config
  79  * \param config pointer to an ast_config data structure
  80  * \param cat name of the category for which you want the root
  81  *
  82  * Returns the category specified
  83  */
  84 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
  85
  86 /*! \brief Goes through categories
  87  * \param config Which config structure you wish to "browse"
  88  * \param prev A pointer to a previous category.
  89  * This funtion is kind of non-intuitive in it's use.  To begin, one passes NULL as the second arguement.  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.
  90  *
  91  * Returns a category on success, or NULL on failure/no-more-categories
  92  */
  93 char *ast_category_browse(struct ast_config *config, const char *prev);
  94
  95 /*! \brief Goes through variables
  96  * Somewhat similar in intent as the ast_category_browse.
  97  * List variables of config file category
  98  *
  99  * Returns ast_variable list on success, or NULL on failure
 100  */
 101 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
 102
 103 /*! \brief Gets a variable
 104  * \param config which (opened) config to use
 105  * \param category category under which the variable lies
 106  * \param variable which variable you wish to get the data for
 107  * Goes through a given config file in the given category and searches for the given variable
 108  *
 109  * Returns the variable value on success, or NULL if unable to find it.
 110  */
 111 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
 112
 113 /*! \brief Retrieve a category if it exists
 114  * \param config which config to use
 115  * \param category_name name of the category you're looking for
 116  * This will search through the categories within a given config file for a match.
 117  *
 118  * Returns pointer to category if found, NULL if not.
 119  */
 120 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
 121
 122 /*! \brief Check for category duplicates
 123  * \param config which config to use
 124  * \param category_name name of the category you're looking for
 125  * This will search through the categories within a given config file for a match.
 126  *
 127  * Return non-zero if found
 128  */
 129 int ast_category_exist(const struct ast_config *config, const char *category_name);
 130
 131 /*! \brief Retrieve realtime configuration
 132  * \param family which family/config to lookup
 133  * This will use builtin configuration backends to look up a particular
 134  * entity in realtime and return a variable list of its parameters.  Note
 135  * that unlike the variables in ast_config, the resulting list of variables
 136  * MUST be freed with ast_variables_destroy() as there is no container.
 137  */
 138 struct ast_variable *ast_load_realtime(const char *family, ...);
 139
 140 /*! \brief Retrieve realtime configuration
 141  * \param family which family/config to lookup
 142  * This will use builtin configuration backends to look up a particular
 143  * entity in realtime and return a variable list of its parameters. Unlike
 144  * the ast_load_realtime, this function can return more than one entry and
 145  * is thus stored inside a taditional ast_config structure rather than
 146  * just returning a linked list of variables.
 147  */
 148 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
 149
 150 /*! \brief Update realtime configuration
 151  * \param family which family/config to be updated
 152  * \param keyfield which field to use as the key
 153  * \param lookup which value to look for in the key field to match the entry.
 154  * This function is used to update a parameter in realtime configuration space.
 155  *
 156  */
 157 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
 158
 159 /*! \brief Check if realtime engine is configured for family
 160  * returns 1 if family is configured in realtime and engine exists
 161  * \param family which family/config to be checked
 162 */
 163 int ast_check_realtime(const char *family);
 164
 165 /*! \brief Free variable list
 166  * \param var the linked list of variables to free
 167  * This function frees a list of variables.
 168  */
 169 void ast_variables_destroy(struct ast_variable *var);
 170
 171 /*! \brief Register config engine */
 172 int ast_config_engine_register(struct ast_config_engine *newconfig);
 173
 174 /*! \brief Deegister config engine */
 175 int ast_config_engine_deregister(struct ast_config_engine *del);
 176
 177 int register_config_cli(void);
 178 int read_config_maps(void);
 179
 180 struct ast_config *ast_config_new(void);
 181 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
 182 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
 183 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
 184
 185 struct ast_category *ast_category_new(const char *name);
 186 void ast_category_append(struct ast_config *config, struct ast_category *cat);
 187 int ast_category_delete(struct ast_config *cfg, char *category);
 188 void ast_category_destroy(struct ast_category *cat);
 189 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
 190 void ast_category_rename(struct ast_category *cat, const char *name);
 191
 192 struct ast_variable *ast_variable_new(const char *name, const char *value);
 193 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
 194 int ast_variable_delete(struct ast_category *category, char *variable, char *match);
 195 int ast_variable_update(struct ast_category *category, const char *variable,
 196         const char *value, const char *match, unsigned int object);
 197
 198 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
 199
 200 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, int withcomments);
 201
 202 #if defined(__cplusplus) || defined(c_plusplus)
 203 }
 204 #endif
 205
 206 #endif /* _ASTERISK_CONFIG_H */