fdcd28a40b3ebd5f82fe4a89f6f7000daaab8fa3
[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 "asterisk/inline_api.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 /*!
51  * \brief Types used in ast_realtime_require_field
52  */
53 typedef enum {
54         RQ_INTEGER1,
55         RQ_UINTEGER1,
56         RQ_INTEGER2,
57         RQ_UINTEGER2,
58         RQ_INTEGER3,
59         RQ_UINTEGER3,
60         RQ_INTEGER4,
61         RQ_UINTEGER4,
62         RQ_INTEGER8,
63         RQ_UINTEGER8,
64         RQ_CHAR,
65         RQ_FLOAT,
66         RQ_DATE,
67         RQ_DATETIME,
68 } require_type;
69
70 /*! \brief Structure for variables, used for configurations and for channel variables 
71 */
72 struct ast_variable {
73         const char *name;
74         const char *value;
75         struct ast_variable *next;
76
77         char *file;
78
79         int lineno;
80         int object;             /*!< 0 for variable, 1 for object */
81         int blanklines;         /*!< Number of blanklines following entry */
82         struct ast_comment *precomments;
83         struct ast_comment *sameline;
84         struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
85         char stuff[0];
86 };
87
88 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);
89 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
90 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
91 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
92 typedef int realtime_store(const char *database, const char *table, va_list ap);
93 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
94 typedef int realtime_require(const char *database, const char *table, va_list ap);
95 typedef int realtime_unload(const char *database, const char *table);
96
97 /*! \brief Configuration engine structure, used to define realtime drivers */
98 struct ast_config_engine {
99         char *name;
100         config_load_func *load_func;
101         realtime_var_get *realtime_func;
102         realtime_multi_get *realtime_multi_func;
103         realtime_update *update_func;
104         realtime_store *store_func;
105         realtime_destroy *destroy_func;
106         realtime_require *require_func;
107         realtime_unload *unload_func;
108         struct ast_config_engine *next;
109 };
110
111 /*! \brief Load a config file 
112  * \param filename path of file to open.  If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
113  * Create a config structure from a given configuration file.
114  * \param who_asked The module which is making this request.
115  * \param flags Optional flags:
116  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
117  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
118  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
119  *
120  * \retval an ast_config data structure on success
121  * \retval NULL on error
122  */
123 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
124
125 #define ast_config_load(filename, flags)        ast_config_load2(filename, AST_MODULE, flags)
126
127 /*! \brief Destroys a config 
128  * \param config pointer to config data structure
129  * Free memory associated with a given config
130  *
131  */
132 void ast_config_destroy(struct ast_config *config);
133
134 /*! \brief returns the root ast_variable of a config
135  * \param config pointer to an ast_config data structure
136  * \param cat name of the category for which you want the root
137  *
138  * Returns the category specified
139  */
140 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
141
142 /*! \brief Goes through categories 
143  * \param config Which config structure you wish to "browse"
144  * \param prev A pointer to a previous category.
145  * 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.
146  *
147  * \retval a category on success
148  * \retval NULL on failure/no-more-categories
149  */
150 char *ast_category_browse(struct ast_config *config, const char *prev);
151
152 /*! 
153  * \brief Goes through variables
154  * Somewhat similar in intent as the ast_category_browse.
155  * List variables of config file category
156  *
157  * \retval ast_variable list on success
158  * \retval NULL on failure
159  */
160 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
161
162 /*!
163  * \brief given a pointer to a category, return the root variable.
164  * This is equivalent to ast_variable_browse(), but more efficient if we
165  * already have the struct ast_category * (e.g. from ast_category_get())
166  */
167 struct ast_variable *ast_category_first(struct ast_category *cat);
168
169 /*! 
170  * \brief Gets a variable 
171  * \param config which (opened) config to use
172  * \param category category under which the variable lies
173  * \param variable which variable you wish to get the data for
174  * Goes through a given config file in the given category and searches for the given variable
175  *
176  * \retval The variable value on success 
177  * \retval NULL if unable to find it.
178  */
179 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
180
181 /*! 
182  * \brief Retrieve a category if it exists
183  * \param config which config to use
184  * \param category_name name of the category you're looking for
185  * This will search through the categories within a given config file for a match.
186  *
187  * \retval pointer to category if found
188  * \retval NULL if not.
189  */
190 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
191
192 /*! 
193  * \brief Check for category duplicates 
194  * \param config which config to use
195  * \param category_name name of the category you're looking for
196  * This will search through the categories within a given config file for a match.
197  *
198  * \return non-zero if found
199  */
200 int ast_category_exist(const struct ast_config *config, const char *category_name);
201
202 /*! 
203  * \brief Retrieve realtime configuration 
204  * \param family which family/config to lookup
205  * This will use builtin configuration backends to look up a particular 
206  * entity in realtime and return a variable list of its parameters.  Note
207  * that unlike the variables in ast_config, the resulting list of variables
208  * MUST be freed with ast_variables_destroy() as there is no container.
209  */
210 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
211 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
212
213 /*!
214  * \brief Release any resources cached for a realtime family
215  * \param family which family/config to destroy
216  * Various backends may cache attributes about a realtime data storage
217  * facility; on reload, a front end resource may request to purge that cache.
218  */
219 int ast_unload_realtime(const char *family);
220
221 /*!
222  * \brief Inform realtime what fields that may be stored
223  * \param family which family/config is referenced
224  * This will inform builtin configuration backends that particular fields
225  * may be updated during the use of that configuration section.  This is
226  * mainly to be used during startup routines, to ensure that various fields
227  * exist in the backend.  The backends may take various actions, such as
228  * creating new fields in the data store or warning the administrator that
229  * new fields may need to be created, in order to ensure proper function.
230  */
231 int ast_require_realtime_fields(const char *family, ...) attribute_sentinel;
232
233 /*! 
234  * \brief Retrieve realtime configuration 
235  * \param family which family/config to lookup
236  * This will use builtin configuration backends to look up a particular 
237  * entity in realtime and return a variable list of its parameters. Unlike
238  * the ast_load_realtime, this function can return more than one entry and
239  * is thus stored inside a taditional ast_config structure rather than 
240  * just returning a linked list of variables.
241  */
242 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
243
244 /*! 
245  * \brief Update realtime configuration 
246  * \param family which family/config to be updated
247  * \param keyfield which field to use as the key
248  * \param lookup which value to look for in the key field to match the entry.
249  * This function is used to update a parameter in realtime configuration space.
250  *
251  */
252 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
253
254 /*! 
255  * \brief Create realtime configuration 
256  * \param family which family/config to be created
257  * This function is used to create a parameter in realtime configuration space.
258  *
259  */
260 int ast_store_realtime(const char *family, ...) attribute_sentinel;
261
262 /*! 
263  * \brief Destroy realtime configuration 
264  * \param family which family/config to be destroyed
265  * \param keyfield which field to use as the key
266  * \param lookup which value to look for in the key field to match the entry.
267  * This function is used to destroy an entry in realtime configuration space.
268  * Additional params are used as keys.
269  *
270  */
271 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
272
273 /*! 
274  * \brief Check if realtime engine is configured for family 
275  * \param family which family/config to be checked
276  * \return 1 if family is configured in realtime and engine exists
277 */
278 int ast_check_realtime(const char *family);
279
280 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
281
282 /*! \brief Check if there's any realtime engines loaded */
283 int ast_realtime_enabled(void);
284
285 /*! \brief Free variable list 
286  * \param var the linked list of variables to free
287  * This function frees a list of variables.
288  */
289 void ast_variables_destroy(struct ast_variable *var);
290
291 /*! \brief Register config engine */
292 int ast_config_engine_register(struct ast_config_engine *newconfig);
293
294 /*! \brief Deegister config engine */
295 int ast_config_engine_deregister(struct ast_config_engine *del);
296
297 int register_config_cli(void);
298 int read_config_maps(void);
299
300 struct ast_config *ast_config_new(void);
301 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
302 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
303 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
304
305 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
306 void ast_category_append(struct ast_config *config, struct ast_category *cat);
307
308 /*! 
309  * \brief Inserts new category
310  * \param config which config to use
311  * \param cat newly created category to insert
312  * \param match which category to insert above
313  * This function is used to insert a new category above another category
314  * matching the match parameter.
315  */
316 void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
317 int ast_category_delete(struct ast_config *cfg, const char *category);
318 int ast_category_empty(struct ast_config *cfg, const char *category);
319 void ast_category_destroy(struct ast_category *cat);
320 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
321 void ast_category_rename(struct ast_category *cat, const char *name);
322
323 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
324 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);
325 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
326 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
327 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
328 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
329 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
330 int ast_variable_update(struct ast_category *category, const char *variable, 
331                                                 const char *value, const char *match, unsigned int object);
332
333 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
334
335 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);
336
337 /*! \brief Support code to parse config file arguments
338  *
339  * The function ast_parse_arg() provides a generic interface to parse
340  * strings (e.g. numbers, network addresses and so on) in a flexible
341  * way, e.g. by doing proper error and bound checks, provide default
342  * values, and so on.
343  * The function (described later) takes a string as an argument,
344  * a set of flags to specify the result format and checks to perform,
345  * a pointer to the result, and optionally some additional arguments.
346  * It returns 0 on success, != 0 otherwise.
347  *
348  */
349 enum ast_parse_flags {
350         /* low 4 bits of flags are used for the operand type */
351         PARSE_TYPE      =       0x000f,
352         /* numeric types, with optional default value and bound checks.
353          * Additional arguments are passed by value.
354          */
355         PARSE_INT32     =       0x0001,
356         PARSE_UINT32    =       0x0002,
357         PARSE_DOUBLE    =       0x0003,
358 #if 0   /* not supported yet */
359         PARSE_INT16     =       0x0004,
360         PARSE_UINT16    =       0x0005,
361 #endif
362         /* Returns a struct sockaddr_in, with optional default value
363          * (passed by reference) and port handling (accept, ignore,
364          * require, forbid). The format is 'host.name[:port]'
365          */
366         PARSE_INADDR    =       0x000f,
367
368         /* Other data types can be added as needed */
369
370         /* If PARSE_DEFAULT is set, next argument is a default value
371          * which is returned in case of error. The argument is passed
372          * by value in case of numeric types, by reference in other cases.
373          */
374         PARSE_DEFAULT   =       0x0010, /* assign default on error */
375
376         /* Request a range check, applicable to numbers. Two additional
377          * arguments are passed by value, specifying the low-high end of
378          * the range (inclusive). An error is returned if the value
379          * is outside or inside the range, respectively.
380          */
381         PARSE_IN_RANGE =        0x0020, /* accept values inside a range */
382         PARSE_OUT_RANGE =       0x0040, /* accept values outside a range */
383
384         /* Port handling, for sockaddr_in. accept/ignore/require/forbid
385          * port number after the hostname or address.
386          */
387         PARSE_PORT_MASK =       0x0300, /* 0x000: accept port if present */
388         PARSE_PORT_IGNORE =     0x0100, /* 0x100: ignore port if present */
389         PARSE_PORT_REQUIRE =    0x0200, /* 0x200: require port number */
390         PARSE_PORT_FORBID =     0x0300, /* 0x100: forbid port number */
391 };
392
393 /*! \brief The argument parsing routine.
394  * \param arg the string to parse. It is not modified.
395  * \param flags combination of ast_parse_flags to specify the
396  *      return type and additional checks.
397  * \param result pointer to the result. NULL is valid here, and can
398  *      be used to perform only the validity checks.
399  * \param ... extra arguments are required according to flags.
400  * \retval 0 in case of success, != 0 otherwise.
401  * \retval result returns the parsed value in case of success,
402  *      the default value in case of error, or it is left unchanged
403  *      in case of error and no default specified. Note that in certain
404  *      cases (e.g. sockaddr_in, with multi-field return values) some
405  *      of the fields in result may be changed even if an error occurs.
406  *
407  * Examples of use:
408  *      ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
409  *              &a, -1000, 1000); 
410  *              returns 0, a = 223
411  *      ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
412  *              &a, 9999, 10, 100);
413  *              returns 1, a = 9999
414  *      ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
415  *              returns 1, b unchanged
416  *      ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
417  *              returns 0, sa contains address and port
418  *      ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
419  *              returns 1 because port is missing, sa contains address
420  */
421 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
422         void *result, ...);
423
424 /*
425  * Parsing config file options in C is slightly annoying because we cannot use
426  * string in a switch() statement, yet we need a similar behaviour, with many
427  * branches and a break on a matching one.
428  * The following somehow simplifies the job: we create a block using
429  * the  CV_START and CV_END macros, and then within the block we can run
430  * actions such as "if (condition) { body; break; }"
431  * Additional macros are present to run simple functions (e.g. ast_copy_string)
432  * or to pass arguments to ast_parse_arg()
433  *
434  * As an example:
435
436         CV_START(v->name, v->value);    // start the block
437         CV_STR("foo", x_foo);           // static string
438         CV_DSTR("bar", y_bar);          // malloc'ed string
439         CV_F("bar", ...);               // call a generic function
440         CV_END;                         // end the block
441  */
442
443 /*! \brief the macro to open a block for variable parsing */
444 #define CV_START(__in_var, __in_val)            \
445         do {                                    \
446                 const char *__var = __in_var;   \
447                 const char *__val = __in_val;
448
449 /*! \brief close a variable parsing block */
450 #define CV_END                  } while (0)
451
452 /*! \brief call a generic function if the name matches. */
453 #define CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
454
455 /*! \brief helper macros to assign the value to a BOOL, UINT, static string and
456  * dynamic string
457  */
458 #define CV_BOOL(__x, __dst)     CV_F(__x, (__dst) = ast_true(__val) )
459 #define CV_UINT(__x, __dst)     CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
460 #define CV_STR(__x, __dst)      CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
461 #define CV_DSTR(__x, __dst)     CV_F(__x, if (__dst) ast_free(__dst); __dst = ast_strdup(__val))
462 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
463
464 AST_INLINE_API(
465 int ast_rq_is_int(require_type type),
466 {
467         switch (type) {
468         case RQ_INTEGER1:
469         case RQ_UINTEGER1:
470         case RQ_INTEGER2:
471         case RQ_UINTEGER2:
472         case RQ_INTEGER3:
473         case RQ_UINTEGER3:
474         case RQ_INTEGER4:
475         case RQ_UINTEGER4:
476         case RQ_INTEGER8:
477         case RQ_UINTEGER8:
478                 return 1;
479         default:
480                 return 0;
481         }
482 }
483 )
484
485 #if defined(__cplusplus) || defined(c_plusplus)
486 }
487 #endif
488
489 #endif /* _ASTERISK_CONFIG_H */