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