Fix port parsing in check_via.
[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 struct ast_variable {
74         const char *name;
75         const char *value;
76         struct ast_variable *next;
77
78         char *file;
79
80         int lineno;
81         int object;             /*!< 0 for variable, 1 for object */
82         int blanklines;         /*!< Number of blanklines following entry */
83         struct ast_comment *precomments;
84         struct ast_comment *sameline;
85         struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
86         char stuff[0];
87 };
88
89 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);
90 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, va_list ap);
91 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap);
92 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
93 typedef int realtime_update2(const char *database, const char *table, va_list ap);
94 typedef int realtime_store(const char *database, const char *table, va_list ap);
95 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap);
96
97 /*!
98  * \brief Function pointer called to ensure database schema is properly configured for realtime use
99  * \since 1.6.1
100  */
101 typedef int realtime_require(const char *database, const char *table, va_list ap);
102
103 /*!
104  * \brief Function pointer called to clear the database cache and free resources used for such
105  * \since 1.6.1
106  */
107 typedef int realtime_unload(const char *database, const char *table);
108
109 /*! \brief Configuration engine structure, used to define realtime drivers */
110 struct ast_config_engine {
111         char *name;
112         config_load_func *load_func;
113         realtime_var_get *realtime_func;
114         realtime_multi_get *realtime_multi_func;
115         realtime_update *update_func;
116         realtime_update2 *update2_func;
117         realtime_store *store_func;
118         realtime_destroy *destroy_func;
119         realtime_require *require_func;
120         realtime_unload *unload_func;
121         struct ast_config_engine *next;
122 };
123
124 /*!
125  * \brief Load a config file
126  *
127  * \param filename path of file to open.  If no preceding '/' character,
128  * path is considered relative to AST_CONFIG_DIR
129  * \param who_asked The module which is making this request.
130  * \param flags Optional flags:
131  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
132  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
133  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
134  *
135  * \details
136  * Create a config structure from a given configuration file.
137  *
138  * \return an ast_config data structure on success
139  * \retval NULL on error
140  */
141 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
142
143 /*!
144  * \brief Load a config file
145  *
146  * \param filename path of file to open.  If no preceding '/' character,
147  * path is considered relative to AST_CONFIG_DIR
148  * \param flags Optional flags:
149  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
150  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
151  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
152  *
153  * \details
154  * Create a config structure from a given configuration file.
155  *
156  * \return an ast_config data structure on success
157  * \retval NULL on error
158  */
159 #define ast_config_load(filename, flags)        ast_config_load2(filename, AST_MODULE, flags)
160
161 /*!
162  * \brief Destroys a config
163  *
164  * \param config pointer to config data structure
165  *
166  * \details
167  * Free memory associated with a given config
168  */
169 void ast_config_destroy(struct ast_config *config);
170
171 /*!
172  * \brief returns the root ast_variable of a config
173  *
174  * \param config pointer to an ast_config data structure
175  * \param cat name of the category for which you want the root
176  *
177  * \return the category specified
178  */
179 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
180
181 /*!
182  * \brief Goes through categories
183  *
184  * \param config Which config structure you wish to "browse"
185  * \param prev A pointer to a previous category.
186  *
187  * \details
188  * This function is kind of non-intuitive in it's use.
189  * To begin, one passes NULL as the second argument.
190  * It will return a pointer to the string of the first category in the file.
191  * From here on after, one must then pass the previous usage's return value
192  * as the second pointer, and it will return a pointer to the category name
193  * afterwards.
194  *
195  * \retval a category on success
196  * \retval NULL on failure/no-more-categories
197  */
198 char *ast_category_browse(struct ast_config *config, const char *prev);
199
200 /*!
201  * \brief Goes through variables
202  *
203  * \details
204  * Somewhat similar in intent as the ast_category_browse.
205  * List variables of config file category
206  *
207  * \retval ast_variable list on success
208  * \retval NULL on failure
209  */
210 struct ast_variable *ast_variable_browse(const struct ast_config *config, const char *category);
211
212 /*!
213  * \brief given a pointer to a category, return the root variable.
214  *
215  * \details
216  * This is equivalent to ast_variable_browse(), but more efficient if we
217  * already have the struct ast_category * (e.g. from ast_category_get())
218  */
219 struct ast_variable *ast_category_first(struct ast_category *cat);
220
221 /*!
222  * \brief Gets a variable
223  *
224  * \param config which (opened) config to use
225  * \param category category under which the variable lies
226  * \param variable which variable you wish to get the data for
227  *
228  * \details
229  * Goes through a given config file in the given category and searches for the given variable
230  *
231  * \retval The variable value on success
232  * \retval NULL if unable to find it.
233  */
234 const char *ast_variable_retrieve(const struct ast_config *config, const char *category, const char *variable);
235
236 /*!
237  * \brief Retrieve a category if it exists
238  *
239  * \param config which config to use
240  * \param category_name name of the category you're looking for
241  *
242  * \details
243  * This will search through the categories within a given config file for a match.
244  *
245  * \retval pointer to category if found
246  * \retval NULL if not.
247  */
248 struct ast_category *ast_category_get(const struct ast_config *config, const char *category_name);
249
250 /*!
251  * \brief Check for category duplicates
252  *
253  * \param config which config to use
254  * \param category_name name of the category you're looking for
255  *
256  * \details
257  * This will search through the categories within a given config file for a match.
258  *
259  * \return non-zero if found
260  */
261 int ast_category_exist(const struct ast_config *config, const char *category_name);
262
263 /*!
264  * \brief Retrieve realtime configuration
265  *
266  * \param family which family/config to lookup
267  *
268  * \details
269  * This will use builtin configuration backends to look up a particular
270  * entity in realtime and return a variable list of its parameters.
271  *
272  * \note
273  * Unlike the variables in ast_config, the resulting list of variables
274  * MUST be freed with ast_variables_destroy() as there is no container.
275  *
276  * \note
277  * The difference between these two calls is that ast_load_realtime excludes
278  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
279  *
280  * \note
281  * You should use the constant SENTINEL to terminate arguments, in
282  * order to preserve cross-platform compatibility.
283  */
284 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
285 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
286
287 /*!
288  * \brief Release any resources cached for a realtime family
289  * \since 1.6.1
290  *
291  * \param family which family/config to destroy
292  *
293  * \details
294  * Various backends may cache attributes about a realtime data storage
295  * facility; on reload, a front end resource may request to purge that cache.
296  *
297  * \retval 0 If any cache was purged
298  * \retval -1 If no cache was found
299  */
300 int ast_unload_realtime(const char *family);
301
302 /*!
303  * \brief Inform realtime what fields that may be stored
304  * \since 1.6.1
305  *
306  * \param family which family/config is referenced
307  *
308  * \details
309  * This will inform builtin configuration backends that particular fields
310  * may be updated during the use of that configuration section.  This is
311  * mainly to be used during startup routines, to ensure that various fields
312  * exist in the backend.  The backends may take various actions, such as
313  * creating new fields in the data store or warning the administrator that
314  * new fields may need to be created, in order to ensure proper function.
315  *
316  * The arguments are specified in groups of 3:  column name, column type,
317  * and column size.  The column types are specified as integer constants,
318  * defined by the enum require_type.  Note that the size is specified as
319  * the number of equivalent character fields that a field may take up, even
320  * if a field is otherwise specified as an integer type.  This is due to
321  * the fact that some fields have historically been specified as character
322  * types, even if they contained integer values.
323  *
324  * A family should always specify its fields to the minimum necessary
325  * requirements to fulfill all possible values (within reason; for example,
326  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
327  * Even though values above 32767 seconds are possible, they are unlikely
328  * to be useful, and we should not complain about that size).
329  *
330  * \retval 0 Required fields met specified standards
331  * \retval -1 One or more fields was missing or insufficient
332  *
333  * \note You should use the constant SENTINEL to terminate arguments, in
334  * order to preserve cross-platform compatibility.
335  */
336 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
337
338 /*!
339  * \brief Retrieve realtime configuration
340  *
341  * \param family which family/config to lookup
342  *
343  * \details
344  * This will use builtin configuration backends to look up a particular
345  * entity in realtime and return a variable list of its parameters. Unlike
346  * the ast_load_realtime, this function can return more than one entry and
347  * is thus stored inside a traditional ast_config structure rather than
348  * just returning a linked list of variables.
349  *
350  * \note You should use the constant SENTINEL to terminate arguments, in
351  * order to preserve cross-platform compatibility.
352  */
353 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
354
355 /*!
356  * \brief Update realtime configuration
357  *
358  * \param family which family/config to be updated
359  * \param keyfield which field to use as the key
360  * \param lookup which value to look for in the key field to match the entry.
361  *
362  * \details
363  * This function is used to update a parameter in realtime configuration space.
364  *
365  * \return Number of rows affected, or -1 on error.
366  *
367  * \note You should use the constant SENTINEL to terminate arguments, in
368  * order to preserve cross-platform compatibility.
369  */
370 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
371
372 /*!
373  * \brief Update realtime configuration
374  *
375  * \param family which family/config to be updated
376  *
377  * \details
378  * This function is used to update a parameter in realtime configuration space.
379  * It includes the ability to lookup a row based upon multiple key criteria.
380  * As a result, this function includes two sentinel values, one to terminate
381  * lookup values and the other to terminate the listing of fields to update.
382  *
383  * \return Number of rows affected, or -1 on error.
384  *
385  * \note You should use the constant SENTINEL to terminate arguments, in
386  * order to preserve cross-platform compatibility.
387  */
388 int ast_update2_realtime(const char *family, ...) attribute_sentinel;
389
390 /*!
391  * \brief Create realtime configuration
392  *
393  * \param family which family/config to be created
394  *
395  * \details
396  * This function is used to create a parameter in realtime configuration space.
397  *
398  * \return Number of rows affected, or -1 on error.
399  *
400  * \note
401  * On the MySQL engine only, for reasons of backwards compatibility, the return
402  * value is the insert ID.  This value is nonportable and may be changed in a
403  * future version to match the other engines.
404  *
405  * \note You should use the constant SENTINEL to terminate arguments, in
406  * order to preserve cross-platform compatibility.
407  */
408 int ast_store_realtime(const char *family, ...) attribute_sentinel;
409
410 /*!
411  * \brief Destroy realtime configuration
412  *
413  * \param family which family/config to be destroyed
414  * \param keyfield which field to use as the key
415  * \param lookup which value to look for in the key field to match the entry.
416  *
417  * \details
418  * This function is used to destroy an entry in realtime configuration space.
419  * Additional params are used as keys.
420  *
421  * \return Number of rows affected, or -1 on error.
422  *
423  * \note You should use the constant SENTINEL to terminate arguments, in
424  * order to preserve cross-platform compatibility.
425  */
426 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
427
428 /*!
429  * \brief Check if realtime engine is configured for family
430  * \param family which family/config to be checked
431  * \return 1 if family is configured in realtime and engine exists
432  */
433 int ast_check_realtime(const char *family);
434
435 /*! \brief Check if there's any realtime engines loaded */
436 int ast_realtime_enabled(void);
437
438 /*!
439  * \brief Free variable list
440  * \param var the linked list of variables to free
441  *
442  * \details
443  * This function frees a list of variables.
444  */
445 void ast_variables_destroy(struct ast_variable *var);
446
447 /*!
448  * \brief Register config engine
449  * \retval 1 Always
450  */
451 int ast_config_engine_register(struct ast_config_engine *newconfig);
452
453 /*!
454  * \brief Deregister config engine
455  * \retval 0 Always
456  */
457 int ast_config_engine_deregister(struct ast_config_engine *del);
458
459 /*!
460  * \brief Exposed initialization method for core process
461  *
462  * \details
463  * This method is intended for use only with the core initialization and is
464  * not designed to be called from any user applications.
465  */
466 int register_config_cli(void);
467
468 /*!
469  * \brief Exposed re-initialization method for core process
470  *
471  * \details
472  * This method is intended for use only with the core re-initialization and is
473  * not designed to be called from any user applications.
474  */
475 int read_config_maps(void);
476
477 /*! \brief Create a new base configuration structure */
478 struct ast_config *ast_config_new(void);
479
480 /*!
481  * \brief Retrieve the current category name being built.
482  *
483  * \details
484  * API for backend configuration engines while building a configuration set.
485  */
486 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
487
488 /*!
489  * \brief Set the category within the configuration as being current.
490  *
491  * \details
492  * API for backend configuration engines while building a configuration set.
493  */
494 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
495
496 /*!
497  * \brief Retrieve a configuration variable within the configuration set.
498  *
499  * \details
500  * Retrieves the named variable \p var within category \p cat of configuration
501  * set \p cfg.  If not found, attempts to retrieve the named variable \p var
502  * from within category \em general.
503  *
504  * \return Value of \p var, or NULL if not found.
505  */
506 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
507
508 /*! \brief Create a category structure */
509 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
510 void ast_category_append(struct ast_config *config, struct ast_category *cat);
511
512 /*!
513  * \brief Inserts new category
514  * 
515  * \param config which config to use
516  * \param cat newly created category to insert
517  * \param match which category to insert above
518  *
519  * \details
520  * This function is used to insert a new category above another category
521  * matching the match parameter.
522  */
523 void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
524 int ast_category_delete(struct ast_config *cfg, const char *category);
525
526 /*!
527  * \brief Removes and destroys all variables within a category
528  * \retval 0 if the category was found and emptied
529  * \retval -1 if the category was not found
530  */
531 int ast_category_empty(struct ast_config *cfg, const char *category);
532 void ast_category_destroy(struct ast_category *cat);
533 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
534 void ast_category_rename(struct ast_category *cat, const char *name);
535
536 #ifdef MALLOC_DEBUG
537 struct ast_variable *_ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno);
538 #define ast_variable_new(a, b, c) _ast_variable_new(a, b, c, __FILE__, __PRETTY_FUNCTION__, __LINE__)
539 #else
540 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
541 #endif
542 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);
543 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
544 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
545 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
546 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
547 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
548
549 /*!
550  * \brief Update variable value within a config
551  *
552  * \param category Category element within the config
553  * \param variable Name of the variable to change
554  * \param value New value of the variable
555  * \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
556  * \param object Boolean of whether to make the new variable an object
557  *
558  * \return 0 on success or -1 on failure.
559  */
560 int ast_variable_update(struct ast_category *category, const char *variable,
561                                                 const char *value, const char *match, unsigned int object);
562
563 int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
564 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator) __attribute__((deprecated));
565
566 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);
567
568 /*!
569  * \brief Support code to parse config file arguments
570  *
571  * \details
572  * The function ast_parse_arg() provides a generic interface to parse
573  * strings (e.g. numbers, network addresses and so on) in a flexible
574  * way, e.g. by doing proper error and bound checks, provide default
575  * values, and so on.
576  * The function (described later) takes a string as an argument,
577  * a set of flags to specify the result format and checks to perform,
578  * a pointer to the result, and optionally some additional arguments.
579  *
580  * \return It returns 0 on success, != 0 otherwise.
581  */
582 enum ast_parse_flags {
583         /* low 4 bits of flags are used for the operand type */
584         PARSE_TYPE      =       0x000f,
585         /* numeric types, with optional default value and bound checks.
586          * Additional arguments are passed by value.
587          */
588         PARSE_INT32     =       0x0001,
589         PARSE_UINT32    =       0x0002,
590         PARSE_DOUBLE    =       0x0003,
591 #if 0   /* not supported yet */
592         PARSE_INT16     =       0x0004,
593         PARSE_UINT16    =       0x0005,
594 #endif
595
596         /* Returns a struct ast_sockaddr, with optional default value
597          * (passed by reference) and port handling (accept, ignore,
598          * require, forbid). The format is 'ipaddress[:port]'. IPv6 address
599          * literals need square brackets around them if a port is specified.
600          */
601         PARSE_ADDR      =       0x000e,
602
603         /* Returns a struct sockaddr_in, with optional default value
604          * (passed by reference) and port handling (accept, ignore,
605          * require, forbid). The format is 'host.name[:port]'
606          */
607         PARSE_INADDR    =       0x000f,
608
609         /* Other data types can be added as needed */
610
611         /* If PARSE_DEFAULT is set, next argument is a default value
612          * which is returned in case of error. The argument is passed
613          * by value in case of numeric types, by reference in other cases.
614          */
615         PARSE_DEFAULT   =       0x0010, /* assign default on error */
616
617         /* Request a range check, applicable to numbers. Two additional
618          * arguments are passed by value, specifying the low-high end of
619          * the range (inclusive). An error is returned if the value
620          * is outside or inside the range, respectively.
621          */
622         PARSE_IN_RANGE =        0x0020, /* accept values inside a range */
623         PARSE_OUT_RANGE =       0x0040, /* accept values outside a range */
624
625         /* Port handling, for ast_sockaddr. accept/ignore/require/forbid
626          * port number after the hostname or address.
627          */
628         PARSE_PORT_MASK =       0x0300, /* 0x000: accept port if present */
629         PARSE_PORT_IGNORE =     0x0100, /* 0x100: ignore port if present */
630         PARSE_PORT_REQUIRE =    0x0200, /* 0x200: require port number */
631         PARSE_PORT_FORBID =     0x0300, /* 0x100: forbid port number */
632 };
633
634 /*!
635  * \brief The argument parsing routine.
636  *
637  * \param arg the string to parse. It is not modified.
638  * \param flags combination of ast_parse_flags to specify the
639  *      return type and additional checks.
640  * \param result pointer to the result. NULL is valid here, and can
641  *      be used to perform only the validity checks.
642  * \param ... extra arguments are required according to flags.
643  *
644  * \retval 0 in case of success, != 0 otherwise.
645  * \retval result returns the parsed value in case of success,
646  *      the default value in case of error, or it is left unchanged
647  *      in case of error and no default specified. Note that in certain
648  *      cases (e.g. sockaddr_in, with multi-field return values) some
649  *      of the fields in result may be changed even if an error occurs.
650  *
651  * \details
652  * Examples of use:
653  *      ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
654  *              &a, -1000, 1000);
655  *              returns 0, a = 223
656  *      ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT,
657  *              &a, 9999, 10, 100);
658  *              returns 1, a = 9999
659  *      ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
660  *              returns 1, b unchanged
661  *      ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
662  *              returns 0, sa contains address and port
663  *      ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
664  *              returns 1 because port is missing, sa contains address
665  */
666 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
667         void *result, ...);
668
669 /*
670  * Parsing config file options in C is slightly annoying because we cannot use
671  * string in a switch() statement, yet we need a similar behaviour, with many
672  * branches and a break on a matching one.
673  * The following somehow simplifies the job: we create a block using
674  * the  CV_START and CV_END macros, and then within the block we can run
675  * actions such as "if (condition) { body; break; }"
676  * Additional macros are present to run simple functions (e.g. ast_copy_string)
677  * or to pass arguments to ast_parse_arg()
678  *
679  * As an example:
680
681         CV_START(v->name, v->value);    // start the block
682         CV_STR("foo", x_foo);           // static string
683         CV_DSTR("bar", y_bar);          // malloc'ed string
684         CV_F("bar", ...);               // call a generic function
685         CV_END;                         // end the block
686  */
687
688 /*! \brief the macro to open a block for variable parsing */
689 #define CV_START(__in_var, __in_val)            \
690         do {                                    \
691                 const char *__var = __in_var;   \
692                 const char *__val = __in_val;
693
694 /*! \brief close a variable parsing block */
695 #define CV_END                  } while (0)
696
697 /*! \brief call a generic function if the name matches. */
698 #define CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
699
700 /*!
701  * \brief helper macros to assign the value to a BOOL, UINT, static string and
702  * dynamic string
703  */
704 #define CV_BOOL(__x, __dst)     CV_F(__x, (__dst) = ast_true(__val) )
705 #define CV_UINT(__x, __dst)     CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
706 #define CV_STR(__x, __dst)      CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
707 #define CV_DSTR(__x, __dst)     CV_F(__x, ast_free(__dst); __dst = ast_strdup(__val))
708 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
709
710 /*! \brief Check if require type is an integer type */
711 AST_INLINE_API(
712 int ast_rq_is_int(require_type type),
713 {
714         switch (type) {
715         case RQ_INTEGER1:
716         case RQ_UINTEGER1:
717         case RQ_INTEGER2:
718         case RQ_UINTEGER2:
719         case RQ_INTEGER3:
720         case RQ_UINTEGER3:
721         case RQ_INTEGER4:
722         case RQ_UINTEGER4:
723         case RQ_INTEGER8:
724         case RQ_UINTEGER8:
725                 return 1;
726         default:
727                 return 0;
728         }
729 }
730 )
731
732 #if defined(__cplusplus) || defined(c_plusplus)
733 }
734 #endif
735
736 #endif /* _ASTERISK_CONFIG_H */