Doxygen fixes.
[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 "asterisk/utils.h"
31 #include <stdarg.h>
32
33 struct ast_config;
34
35 struct ast_category;
36
37 /*! Options for ast_config_load()
38  */
39 enum {
40         /*! Load the configuration, including comments */
41         CONFIG_FLAG_WITHCOMMENTS  = (1 << 0),
42         /*! On a reload, give us a -1 if the file hasn't changed. */
43         CONFIG_FLAG_FILEUNCHANGED = (1 << 1),
44         /*! Don't attempt to cache mtime on this config file. */
45         CONFIG_FLAG_NOCACHE       = (1 << 2),
46 };
47
48 #define CONFIG_STATUS_FILEUNCHANGED     (void *)-1
49
50 /*! \brief Structure for variables, used for configurations and for channel variables 
51 */
52 struct ast_variable {
53         char *name;
54         char *value;
55         char *file;
56         int lineno;
57         int object;             /*!< 0 for variable, 1 for object */
58         int blanklines;         /*!< Number of blanklines following entry */
59         struct ast_comment *precomments;
60         struct ast_comment *sameline;
61         struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
62         struct ast_variable *next;
63         char stuff[0];
64 };
65
66 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);
67 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
68 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
69 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
70 typedef int realtime_store(const char *database, const char *table, va_list ap);
71 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
72
73 /*! \brief Configuration engine structure, used to define realtime drivers */
74 struct ast_config_engine {
75         char *name;
76         config_load_func *load_func;
77         realtime_var_get *realtime_func;
78         realtime_multi_get *realtime_multi_func;
79         realtime_update *update_func;
80         realtime_store *store_func;
81         realtime_destroy *destroy_func;
82         struct ast_config_engine *next;
83 };
84
85 /*! \brief Load a config file 
86  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
87  * Create a config structure from a given configuration file.
88  * \param flags Optional flags:
89  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
90  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
91  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
92  *
93  * \retval an ast_config data structure on success
94  * \retval NULL on error
95  */
96 struct ast_config *ast_config_load(const char *filename, struct ast_flags flags);
97
98 /*! \brief Destroys a config 
99  * \param config pointer to config data structure
100  * Free memory associated with a given config
101  *
102  */
103 void ast_config_destroy(struct ast_config *config);
104
105 /*! \brief returns the root ast_variable of a config
106  * \param config pointer to an ast_config data structure
107  * \param cat name of the category for which you want the root
108  *
109  * Returns the category specified
110  */
111 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
112
113 /*! \brief Goes through categories 
114  * \param config Which config structure you wish to "browse"
115  * \param prev A pointer to a previous category.
116  * 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.
117  *
118  * \retval a category on success
119  * \retval NULL on failure/no-more-categories
120  */
121 char *ast_category_browse(struct ast_config *config, const char *prev);
122
123 /*! 
124  * \brief Goes through variables
125  * Somewhat similar in intent as the ast_category_browse.
126  * List variables of config file category
127  *
128  * \retval ast_variable list on success
129  * \retval NULL on failure
130  */
131 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
132
133 /*! 
134  * \brief Gets a variable 
135  * \param config which (opened) config to use
136  * \param category category under which the variable lies
137  * \param variable which variable you wish to get the data for
138  * Goes through a given config file in the given category and searches for the given variable
139  *
140  * \retval The variable value on success 
141  * \retval NULL if unable to find it.
142  */
143 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
144
145 /*! 
146  * \brief Retrieve a category if it exists
147  * \param config which config to use
148  * \param category_name name of the category you're looking for
149  * This will search through the categories within a given config file for a match.
150  *
151  * \retval pointer to category if found
152  * \retval NULL if not.
153  */
154 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
155
156 /*! 
157  * \brief Check for category duplicates 
158  * \param config which config to use
159  * \param category_name name of the category you're looking for
160  * This will search through the categories within a given config file for a match.
161  *
162  * \return non-zero if found
163  */
164 int ast_category_exist(const struct ast_config *config, const char *category_name);
165
166 /*! 
167  * \brief Retrieve realtime configuration 
168  * \param family which family/config to lookup
169  * This will use builtin configuration backends to look up a particular 
170  * entity in realtime and return a variable list of its parameters.  Note
171  * that unlike the variables in ast_config, the resulting list of variables
172  * MUST be freed with ast_variables_destroy() as there is no container.
173  */
174 struct ast_variable *ast_load_realtime(const char *family, ...);
175 struct ast_variable *ast_load_realtime_all(const char *family, ...);
176
177 /*! 
178  * \brief Retrieve realtime configuration 
179  * \param family which family/config to lookup
180  * This will use builtin configuration backends to look up a particular 
181  * entity in realtime and return a variable list of its parameters. Unlike
182  * the ast_load_realtime, this function can return more than one entry and
183  * is thus stored inside a taditional ast_config structure rather than 
184  * just returning a linked list of variables.
185  */
186 struct ast_config *ast_load_realtime_multientry(const char *family, ...);
187
188 /*! 
189  * \brief Update realtime configuration 
190  * \param family which family/config to be updated
191  * \param keyfield which field to use as the key
192  * \param lookup which value to look for in the key field to match the entry.
193  * This function is used to update a parameter in realtime configuration space.
194  *
195  */
196 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...);
197
198 /*! 
199  * \brief Create realtime configuration 
200  * \param family which family/config to be created
201  * This function is used to create a parameter in realtime configuration space.
202  *
203  */
204 int ast_store_realtime(const char *family, ...);
205
206 /*! 
207  * \brief Destroy realtime configuration 
208  * \param family which family/config to be destroyed
209  * \param keyfield which field to use as the key
210  * \param lookup which value to look for in the key field to match the entry.
211  * This function is used to destroy an entry in realtime configuration space.
212  * Additional params are used as keys.
213  *
214  */
215 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...);
216
217 /*! 
218  * \brief Check if realtime engine is configured for family 
219  * \param family which family/config to be checked
220  * \return 1 if family is configured in realtime and engine exists
221 */
222 int ast_check_realtime(const char *family);
223
224 /*! \brief Check if there's any realtime engines loaded */
225 int ast_realtime_enabled(void);
226
227 /*! \brief Free variable list 
228  * \param var the linked list of variables to free
229  * This function frees a list of variables.
230  */
231 void ast_variables_destroy(struct ast_variable *var);
232
233 /*! \brief Register config engine */
234 int ast_config_engine_register(struct ast_config_engine *newconfig);
235
236 /*! \brief Deegister config engine */
237 int ast_config_engine_deregister(struct ast_config_engine *del);
238
239 int register_config_cli(void);
240 int read_config_maps(void);
241
242 struct ast_config *ast_config_new(void);
243 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
244 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
245 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
246
247 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
248 void ast_category_append(struct ast_config *config, struct ast_category *cat);
249 int ast_category_delete(struct ast_config *cfg, const char *category);
250 void ast_category_destroy(struct ast_category *cat);
251 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
252 void ast_category_rename(struct ast_category *cat, const char *name);
253
254 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
255 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);
256 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
257 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
258 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
259 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match);
260 int ast_variable_update(struct ast_category *category, const char *variable, 
261                                                 const char *value, const char *match, unsigned int object);
262
263 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
264
265 struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, struct ast_flags flags, const char *suggested_incl_file);
266 /*! \brief Support code to parse config file arguments
267  *
268  * The function ast_parse_arg() provides a generic interface to parse
269  * strings (e.g. numbers, network addresses and so on) in a flexible
270  * way, e.g. by doing proper error and bound checks, provide default
271  * values, and so on.
272  * The function (described later) takes a string as an argument,
273  * a set of flags to specify the result format and checks to perform,
274  * a pointer to the result, and optionally some additional arguments.
275  * It returns 0 on success, != 0 otherwise.
276  *
277  */
278 enum ast_parse_flags {
279         /* low 4 bits of flags are used for the operand type */
280         PARSE_TYPE      =       0x000f,
281         /* numeric types, with optional default value and bound checks.
282          * Additional arguments are passed by value.
283          */
284         PARSE_INT16     =       0x0001,
285         PARSE_INT32     =       0x0002,
286         PARSE_UINT16    =       0x0003,
287         PARSE_UINT32    =       0x0004,
288         /* Returns a struct sockaddr_in, with optional default value
289          * (passed by reference) and port handling (accept, ignore,
290          * require, forbid). The format is 'host.name[:port]'
291          */
292         PARSE_INADDR    =       0x0005,
293
294         /* Other data types can be added as needed */
295
296         /* If PARSE_DEFAULT is set, next argument is a default value
297          * which is returned in case of error. The argument is passed
298          * by value in case of numeric types, by reference in other cases.
299          */
300         PARSE_DEFAULT   =       0x0010, /* assign default on error */
301
302         /* Request a range check, applicable to numbers. Two additional
303          * arguments are passed by value, specifying the low-high end of
304          * the range (inclusive). An error is returned if the value
305          * is outside or inside the range, respectively.
306          */
307         PARSE_IN_RANGE =        0x0020, /* accept values inside a range */
308         PARSE_OUT_RANGE =       0x0040, /* accept values outside a range */
309
310         /* Port handling, for sockaddr_in. accept/ignore/require/forbid
311          * port number after the hostname or address.
312          */
313         PARSE_PORT_MASK =       0x0300, /* 0x000: accept port if present */
314         PARSE_PORT_IGNORE =     0x0100, /* 0x100: ignore port if present */
315         PARSE_PORT_REQUIRE =    0x0200, /* 0x200: require port number */
316         PARSE_PORT_FORBID =     0x0300, /* 0x100: forbid port number */
317 };
318
319 /*! \brief The argument parsing routine.
320  * \param arg the string to parse. It is not modified.
321  * \param flags combination of ast_parse_flags to specify the
322  *      return type and additional checks.
323  * \param result pointer to the result. NULL is valid here, and can
324  *      be used to perform only the validity checks.
325  * \param ... extra arguments are required according to flags.
326  * \retval 0 in case of success, != 0 otherwise.
327  * \retval result returns the parsed value in case of success,
328  *      the default value in case of error, or it is left unchanged
329  *      in case of error and no default specified. Note that in certain
330  *      cases (e.g. sockaddr_in, with multi-field return values) some
331  *      of the fields in result may be changed even if an error occurs.
332  *
333  * Examples of use:
334  *      ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
335  *              &a, -1000, 1000); 
336  *              returns 0, a = 223
337  *      ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
338  *              &a, 9999, 10, 100);
339  *              returns 1, a = 9999
340  *      ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
341  *              returns 1, b unchanged
342  *      ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
343  *              returns 0, sa contains address and port
344  *      ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
345  *              returns 1 because port is missing, sa contains address
346  */
347 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
348         void *result, ...);
349
350 #if defined(__cplusplus) || defined(c_plusplus)
351 }
352 #endif
353
354 #endif /* _ASTERISK_CONFIG_H */