5e1a6fc72bc1423f9193c495a53a56a4ab4b0a83
[asterisk/asterisk.git] / 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 /*! \brief Structure for variables, used for configurations and for channel variables 
37 */
38 struct ast_variable {
39         char *name;
40         char *value;
41         int lineno;
42         int object;             /*!< 0 for variable, 1 for object */
43         int blanklines;         /*!< Number of blanklines following entry */
44         struct ast_comment *precomments;
45         struct ast_comment *sameline;
46         struct ast_variable *next;
47         char stuff[0];
48 };
49
50 typedef struct ast_config *config_load_func(const char *database, const char *table, const char *configfile, struct ast_config *config, int withcomments);
51 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
52 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
53 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
54
55 /*! \brief Configuration engine structure, used to define realtime drivers */
56 struct ast_config_engine {
57         char *name;
58         config_load_func *load_func;
59         realtime_var_get *realtime_func;
60         realtime_multi_get *realtime_multi_func;
61         realtime_update *update_func;
62         struct ast_config_engine *next;
63 };
64
65 /*! \brief Load a config file 
66  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
67  * Create a config structure from a given configuration file.
68  *
69  * Returns NULL on error, or an ast_config data structure on success
70  */
71 struct ast_config *ast_config_load(const char *filename);
72 struct ast_config *ast_config_load_with_comments(const char *filename);
73
74 /*! \brief Destroys a config 
75  * \param config pointer to config data structure
76  * Free memory associated with a given config
77  *
78  */
79 void ast_config_destroy(struct ast_config *config);
80
81 /*! \brief Goes through categories 
82  * \param config Which config structure you wish to "browse"
83  * \param prev A pointer to a previous category.
84  * 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.
85  *
86  * Returns a category on success, or NULL on failure/no-more-categories
87  */
88 char *ast_category_browse(struct ast_config *config, const char *prev);
89
90 /*! \brief Goes through variables
91  * Somewhat similar in intent as the ast_category_browse.
92  * List variables of config file category
93  *
94  * Returns ast_variable list on success, or NULL on failure
95  */
96 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
97
98 /*! \brief Gets a variable 
99  * \param config which (opened) config to use
100  * \param category category under which the variable lies
101  * \param variable which variable you wish to get the data for
102  * Goes through a given config file in the given category and searches for the given variable
103  *
104  * Returns the variable value on success, or NULL if unable to find it.
105  */
106 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
107
108 /*! \brief Retrieve a category if it exists
109  * \param config which config to use
110  * \param category_name name of the category you're looking for
111  * This will search through the categories within a given config file for a match.
112  *
113  * Returns pointer to category if found, NULL if not.
114  */
115 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
116
117 /*! \brief Check for category duplicates 
118  * \param config which config to use
119  * \param category_name name of the category you're looking for
120  * This will search through the categories within a given config file for a match.
121  *
122  * Return non-zero if found
123  */
124 int ast_category_exist(const struct ast_config *config, const char *category_name);
125
126 /*! \brief Retrieve realtime configuration 
127  * \param family which family/config to lookup
128  * This will use builtin configuration backends to look up a particular 
129  * entity in realtime and return a variable list of its parameters.  Note
130  * that unlike the variables in ast_config, the resulting list of variables
131  * MUST be freed with ast_variables_destroy() as there is no container.
132  */
133 struct ast_variable *ast_load_realtime(const char *family, ...);
134 struct ast_variable *ast_load_realtime_all(const char *family, ...);
135
136 /*! \brief Retrieve realtime configuration 
137  * \param family which family/config to lookup
138  * This will use builtin configuration backends to look up a particular 
139  * entity in realtime and return a variable list of its parameters. Unlike
140  * the ast_load_realtime, this function can return more than one entry and
141  * is thus stored inside a taditional ast_config structure rather than 
142  * just returning a linked list of variables.
143  */
144 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
145
146 /*! \brief Update realtime configuration 
147  * \param family which family/config to be updated
148  * \param keyfield which field to use as the key
149  * \param lookup which value to look for in the key field to match the entry.
150  * This function is used to update a parameter in realtime configuration space.
151  *
152  */
153 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
154
155 /*! \brief Check if realtime engine is configured for family 
156  * returns 1 if family is configured in realtime and engine exists
157  * \param family which family/config to be checked
158 */
159 int ast_check_realtime(const char *family);
160
161 /*! \brief Check if there's any realtime engines loaded */
162 int ast_realtime_enabled(void);
163
164 /*! \brief Free variable list 
165  * \param var the linked list of variables to free
166  * This function frees a list of variables.
167  */
168 void ast_variables_destroy(struct ast_variable *var);
169
170 /*! \brief Register config engine */
171 int ast_config_engine_register(struct ast_config_engine *newconfig);
172
173 /*! \brief Deegister config engine */
174 int ast_config_engine_deregister(struct ast_config_engine *del);
175
176 int register_config_cli(void);
177 int read_config_maps(void);
178
179 struct ast_config *ast_config_new(void);
180 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
181 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
182 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
183
184 struct ast_category *ast_category_new(const char *name);
185 void ast_category_append(struct ast_config *config, struct ast_category *cat);
186 int ast_category_delete(struct ast_config *cfg, const char *category);
187 void ast_category_destroy(struct ast_category *cat);
188 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
189 void ast_category_rename(struct ast_category *cat, const char *name);
190
191 struct ast_variable *ast_variable_new(const char *name, const char *value);
192 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
193 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match);
194 int ast_variable_update(struct ast_category *category, const char *variable, const char *value, const char *match);
195
196 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
197
198 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, int withcomments);
199
200 #if defined(__cplusplus) || defined(c_plusplus)
201 }
202 #endif
203
204 #endif /* _ASTERISK_CONFIG_H */