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