manager/config: Support templates and non-unique category names via AMI
[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         /*! Don't attempt to load from realtime (typically called from a realtime driver dependency) */
47         CONFIG_FLAG_NOREALTIME    = (1 << 3),
48 };
49
50 #define CONFIG_STATUS_FILEMISSING       (void *)0
51 #define CONFIG_STATUS_FILEUNCHANGED     (void *)-1
52 #define CONFIG_STATUS_FILEINVALID       (void *)-2
53
54 /*!
55  * \brief Types used in ast_realtime_require_field
56  */
57 typedef enum {
58         RQ_INTEGER1,
59         RQ_UINTEGER1,
60         RQ_INTEGER2,
61         RQ_UINTEGER2,
62         RQ_INTEGER3,
63         RQ_UINTEGER3,
64         RQ_INTEGER4,
65         RQ_UINTEGER4,
66         RQ_INTEGER8,
67         RQ_UINTEGER8,
68         RQ_CHAR,
69         RQ_FLOAT,
70         RQ_DATE,
71         RQ_DATETIME,
72 } require_type;
73
74 /*! \brief Structure for variables, used for configurations and for channel variables */
75 struct ast_variable {
76         /*! Variable name.  Stored in stuff[] at struct end. */
77         const char *name;
78         /*! Variable value.  Stored in stuff[] at struct end. */
79         const char *value;
80
81         /*! Next node in the list. */
82         struct ast_variable *next;
83
84         /*! Filename where variable found.  Stored in stuff[] at struct end. */
85         const char *file;
86
87         int lineno;
88         int object;             /*!< 0 for variable, 1 for object */
89         int blanklines;         /*!< Number of blanklines following entry */
90         struct ast_comment *precomments;
91         struct ast_comment *sameline;
92         struct ast_comment *trailing; /*!< the last object in the list will get assigned any trailing comments when EOF is hit */
93         /*!
94          * \brief Contents of file, name, and value in that order stuffed here.
95          * \note File must be stuffed before name because of ast_include_rename().
96          */
97         char stuff[0];
98 };
99
100 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);
101 typedef struct ast_variable *realtime_var_get(const char *database, const char *table, const struct ast_variable *fields);
102 typedef struct ast_config *realtime_multi_get(const char *database, const char *table, const struct ast_variable *fields);
103 typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields);
104 typedef int realtime_update2(const char *database, const char *table, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields);
105 typedef int realtime_store(const char *database, const char *table, const struct ast_variable *fields);
106 typedef int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields);
107
108 /*!
109  * \brief Function pointer called to ensure database schema is properly configured for realtime use
110  * \since 1.6.1
111  */
112 typedef int realtime_require(const char *database, const char *table, va_list ap);
113
114 /*!
115  * \brief Function pointer called to clear the database cache and free resources used for such
116  * \since 1.6.1
117  */
118 typedef int realtime_unload(const char *database, const char *table);
119
120 /*! \brief Configuration engine structure, used to define realtime drivers */
121 struct ast_config_engine {
122         char *name;
123         config_load_func *load_func;
124         realtime_var_get *realtime_func;
125         realtime_multi_get *realtime_multi_func;
126         realtime_update *update_func;
127         realtime_update2 *update2_func;
128         realtime_store *store_func;
129         realtime_destroy *destroy_func;
130         realtime_require *require_func;
131         realtime_unload *unload_func;
132         struct ast_config_engine *next;
133 };
134
135 /*!
136  * \brief Load a config file
137  *
138  * \param filename path of file to open.  If no preceding '/' character,
139  * path is considered relative to AST_CONFIG_DIR
140  * \param who_asked The module which is making this request.
141  * \param flags Optional flags:
142  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
143  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
144  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
145  *
146  * \details
147  * Create a config structure from a given configuration file.
148  *
149  * \return an ast_config data structure on success
150  * \retval NULL on error
151  */
152 struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
153
154 /*!
155  * \brief Load a config file
156  *
157  * \param filename path of file to open.  If no preceding '/' character,
158  * path is considered relative to AST_CONFIG_DIR
159  * \param flags Optional flags:
160  * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
161  * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
162  * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
163  *
164  * \details
165  * Create a config structure from a given configuration file.
166  *
167  * \return an ast_config data structure on success
168  * \retval NULL on error
169  */
170 #define ast_config_load(filename, flags)        ast_config_load2(filename, AST_MODULE, flags)
171
172 /*!
173  * \brief Destroys a config
174  *
175  * \param config pointer to config data structure
176  *
177  * \details
178  * Free memory associated with a given config
179  */
180 void ast_config_destroy(struct ast_config *config);
181
182 /*!
183  * \brief returns the root ast_variable of a config
184  *
185  * \param config pointer to an ast_config data structure
186  * \param cat name of the category for which you want the root
187  *
188  * \return the category specified
189  */
190 struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
191
192 /*!
193  * \brief Sorts categories in a config in the order of a numerical value contained within them.
194  *
195  * \param config The config structure you wish to sort
196  * \param comparator variable Which numerical value you wish to sort by
197  * \param descending If true, we sort highest to lowest instead of lowest to highest
198  *
199  * \details
200  * This function will assume a value of 0 for any non-numerical strings and NULL fields.
201  */
202 void ast_config_sort_categories(struct ast_config *config, int descending,
203                                                                 int (*comparator)(struct ast_category *p, struct ast_category *q));
204
205 /*!
206  * \brief Browse categories with filters
207  *
208  * \param config Which config structure you wish to "browse"
209  * \param category_name An optional category name.
210  * Pass NULL to not restrict by category name.
211  * \param prev A pointer to the starting category structure.
212  * Pass NULL to start at the beginning.
213  * \param filter An optional comma-separated list of <name_regex>=<value_regex>
214  * pairs.  Only categories with matching variables will be returned.
215  * The special name 'TEMPLATES' can be used with the special values
216  * 'include' or 'restrict' to include templates in the result or
217  * restrict the result to only templates.
218  *
219  * \retval a category on success
220  * \retval NULL on failure/no-more-categories
221  */
222 struct ast_category *ast_category_browse_filtered(struct ast_config *config,
223         const char *category_name, struct ast_category *prev, const char *filter);
224
225 /*!
226  * \brief Browse categories
227  *
228  * \param config Which config structure you wish to "browse"
229  * \param prev_name A pointer to a previous category name.
230  *
231  * \details
232  * This function is kind of non-intuitive in it's use.
233  * To begin, one passes NULL as the second argument.
234  * It will return a pointer to the string of the first category in the file.
235  * From here on after, one must then pass the previous usage's return value
236  * as the second pointer, and it will return a pointer to the category name
237  * afterwards.
238  *
239  * \retval a category name on success
240  * \retval NULL on failure/no-more-categories
241  */
242 char *ast_category_browse(struct ast_config *config, const char *prev_name);
243
244 /*!
245  * \brief Browse variables
246  * \param config Which config structure you wish to "browse"
247  * \param category_name Which category to "browse"
248  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
249  * pairs.  Only categories with matching variables will be browsed.
250  * The special name 'TEMPLATES' can be used with the special values
251  * 'include' or 'restrict' to include templates in the result or
252  * restrict the result to only templates.
253  *
254  * \details
255  * Somewhat similar in intent as the ast_category_browse.
256  * List variables of config file category
257  *
258  * \retval ast_variable list on success
259  * \retval NULL on failure
260  */
261 struct ast_variable *ast_variable_browse_filtered(const struct ast_config *config,
262         const char *category_name, const char *filter);
263 struct ast_variable *ast_variable_browse(const struct ast_config *config,
264         const char *category_name);
265
266 /*!
267  * \brief given a pointer to a category, return the root variable.
268  *
269  * \details
270  * This is equivalent to ast_variable_browse(), but more efficient if we
271  * already have the struct ast_category * (e.g. from ast_category_get())
272  */
273 struct ast_variable *ast_category_first(struct ast_category *cat);
274
275 /*!
276  * \brief Gets a variable by context and variable names
277  *
278  * \param config which (opened) config to use
279  * \param category category under which the variable lies
280  * \param variable which variable you wish to get the data for
281  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
282  * pairs.  Only categories with matching variables will be searched.
283  * The special name 'TEMPLATES' can be used with the special values
284  * 'include' or 'restrict' to include templates in the result or
285  * restrict the result to only templates.
286  *
287  * \retval The variable value on success
288  * \retval NULL if unable to find it.
289  */
290 const char *ast_variable_retrieve_filtered(struct ast_config *config,
291         const char *category, const char *variable, const char *filter);
292 const char *ast_variable_retrieve(struct ast_config *config,
293         const char *category, const char *variable);
294
295 /*!
296  * \brief Gets a variable from a specific category structure
297  *
298  * \param category category structure under which the variable lies
299  * \param variable which variable you wish to get the data for
300  *
301  * \details
302  * Goes through a given category and searches for the given variable
303  *
304  * \retval The variable value on success
305  * \retval NULL if unable to find it.
306  */
307 const char *ast_variable_find(const struct ast_category *category, const char *variable);
308
309 /*!
310  * \brief Retrieve a category if it exists
311  *
312  * \param config which config to use
313  * \param category_name name of the category you're looking for
314  * \param filter If a config contains more than 1 category with the same name,
315  * you can specify a filter to narrow the search.  The filter is a comma-separated
316  * list of <name_regex>=<value_regex> pairs.  Only a category with matching
317  * variables will be returned. The special name 'TEMPLATES' can be used with the
318  * special values 'include' or 'restrict' to include templates in the result or
319  * restrict the result to only templates.
320  *
321  * \details
322  * This will search through the categories within a given config file for a match.
323  *
324  * \retval pointer to category if found
325  * \retval NULL if not.
326  */
327 struct ast_category *ast_category_get(const struct ast_config *config,
328         const char *category_name, const char *filter);
329
330 /*!
331  * \brief Return the name of the category
332  *
333  * \param category category structure
334  *
335  * \retval pointer to category name if found
336  * \retval NULL if not.
337  */
338 const char *ast_category_get_name(const struct ast_category *category);
339
340 /*!
341  * \brief Check if category is a template
342  *
343  * \param category category structure
344  *
345  * \retval 1 if a template.
346  * \retval 0 if not.
347  */
348 int ast_category_is_template(const struct ast_category *category);
349
350 /*!
351  * \brief Return the template names this category inherits from
352  *
353  * \param category category structure
354  *
355  * \return an ast_str (which must be freed after use) with a comma
356  * separated list of templates names or NULL if there were no templates.
357  */
358 struct ast_str *ast_category_get_templates(const struct ast_category *category);
359
360 /*!
361  * \brief Check for category duplicates
362  *
363  * \param config which config to use
364  * \param category_name name of the category you're looking for
365  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
366  * pairs.  Only categories with matching variables will be returned.
367  * The special name 'TEMPLATES' can be used with the special values
368  * 'include' or 'restrict' to include templates in the result or
369  * restrict the result to only templates.
370  *
371  * \details
372  * This will search through the categories within a given config file for a match.
373  *
374  * \return non-zero if found
375  */
376 int ast_category_exist(const struct ast_config *config, const char *category_name,
377         const char *filter);
378
379 /*!
380  * \brief Retrieve realtime configuration
381  *
382  * \param family which family/config to lookup
383  *
384  * \details
385  * This will use builtin configuration backends to look up a particular
386  * entity in realtime and return a variable list of its parameters.
387  *
388  * \note
389  * Unlike the variables in ast_config, the resulting list of variables
390  * MUST be freed with ast_variables_destroy() as there is no container.
391  *
392  * \note
393  * The difference between these two calls is that ast_load_realtime excludes
394  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
395  *
396  * \note
397  * You should use the constant SENTINEL to terminate arguments, in
398  * order to preserve cross-platform compatibility.
399  */
400 struct ast_variable *ast_load_realtime_fields(const char *family, const struct ast_variable *fields);
401 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
402 struct ast_variable *ast_load_realtime_all_fields(const char *family, const struct ast_variable *fields);
403 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
404
405 /*!
406  * \brief Release any resources cached for a realtime family
407  * \since 1.6.1
408  *
409  * \param family which family/config to destroy
410  *
411  * \details
412  * Various backends may cache attributes about a realtime data storage
413  * facility; on reload, a front end resource may request to purge that cache.
414  *
415  * \retval 0 If any cache was purged
416  * \retval -1 If no cache was found
417  */
418 int ast_unload_realtime(const char *family);
419
420 /*!
421  * \brief Inform realtime what fields that may be stored
422  * \since 1.6.1
423  *
424  * \param family which family/config is referenced
425  *
426  * \details
427  * This will inform builtin configuration backends that particular fields
428  * may be updated during the use of that configuration section.  This is
429  * mainly to be used during startup routines, to ensure that various fields
430  * exist in the backend.  The backends may take various actions, such as
431  * creating new fields in the data store or warning the administrator that
432  * new fields may need to be created, in order to ensure proper function.
433  *
434  * The arguments are specified in groups of 3:  column name, column type,
435  * and column size.  The column types are specified as integer constants,
436  * defined by the enum require_type.  Note that the size is specified as
437  * the number of equivalent character fields that a field may take up, even
438  * if a field is otherwise specified as an integer type.  This is due to
439  * the fact that some fields have historically been specified as character
440  * types, even if they contained integer values.
441  *
442  * A family should always specify its fields to the minimum necessary
443  * requirements to fulfill all possible values (within reason; for example,
444  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
445  * Even though values above 32767 seconds are possible, they are unlikely
446  * to be useful, and we should not complain about that size).
447  *
448  * \retval 0 Required fields met specified standards
449  * \retval -1 One or more fields was missing or insufficient
450  *
451  * \note You should use the constant SENTINEL to terminate arguments, in
452  * order to preserve cross-platform compatibility.
453  */
454 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
455
456 /*!
457  * \brief Retrieve realtime configuration
458  *
459  * \param family which family/config to lookup
460  * \param fields list of fields
461  *
462  * \details
463  * This will use builtin configuration backends to look up a particular
464  * entity in realtime and return a variable list of its parameters. Unlike
465  * the ast_load_realtime, this function can return more than one entry and
466  * is thus stored inside a traditional ast_config structure rather than
467  * just returning a linked list of variables.
468  *
469  * \return An ast_config with one or more results
470  * \retval NULL Error or no results returned
471  */
472 struct ast_config *ast_load_realtime_multientry_fields(const char *family, const struct ast_variable *fields);
473
474 /*!
475  * \brief Retrieve realtime configuration
476  *
477  * \param family which family/config to lookup
478  *
479  * \details
480  * This will use builtin configuration backends to look up a particular
481  * entity in realtime and return a variable list of its parameters. Unlike
482  * the ast_load_realtime, this function can return more than one entry and
483  * is thus stored inside a traditional ast_config structure rather than
484  * just returning a linked list of variables.
485  *
486  * \return An ast_config with one or more results
487  * \retval NULL Error or no results returned
488  *
489  * \note You should use the constant SENTINEL to terminate arguments, in
490  * order to preserve cross-platform compatibility.
491  */
492 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
493
494 /*!
495  * \brief Update realtime configuration
496  *
497  * \param family which family/config to be updated
498  * \param keyfield which field to use as the key
499  * \param lookup which value to look for in the key field to match the entry.
500  * \param fields fields to update
501  *
502  * \details
503  * This function is used to update a parameter in realtime configuration space.
504  *
505  * \return Number of rows affected, or -1 on error.
506  */
507 int ast_update_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
508
509 /*!
510  * \brief Update realtime configuration
511  *
512  * \param family which family/config to be updated
513  * \param keyfield which field to use as the key
514  * \param lookup which value to look for in the key field to match the entry.
515  *
516  * \details
517  * This function is used to update a parameter in realtime configuration space.
518  *
519  * \return Number of rows affected, or -1 on error.
520  *
521  * \note You should use the constant SENTINEL to terminate arguments, in
522  * order to preserve cross-platform compatibility.
523  */
524 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
525
526 /*!
527  * \brief Update realtime configuration
528  *
529  * \param family which family/config to be updated
530  * \param lookup_fields fields used to look up entries
531  * \param update_fields fields to update
532  *
533  * \details
534  * This function is used to update a parameter in realtime configuration space.
535  * It includes the ability to lookup a row based upon multiple key criteria.
536  * As a result, this function includes two sentinel values, one to terminate
537  * lookup values and the other to terminate the listing of fields to update.
538  *
539  * \return Number of rows affected, or -1 on error.
540  */
541 int ast_update2_realtime_fields(const char *family, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields);
542
543 /*!
544  * \brief Update realtime configuration
545  *
546  * \param family which family/config to be updated
547  *
548  * \details
549  * This function is used to update a parameter in realtime configuration space.
550  * It includes the ability to lookup a row based upon multiple key criteria.
551  * As a result, this function includes two sentinel values, one to terminate
552  * lookup values and the other to terminate the listing of fields to update.
553  *
554  * \return Number of rows affected, or -1 on error.
555  *
556  * \note You should use the constant SENTINEL to terminate arguments, in
557  * order to preserve cross-platform compatibility.
558  */
559 int ast_update2_realtime(const char *family, ...) attribute_sentinel;
560
561 /*!
562  * \brief Create realtime configuration
563  *
564  * \param family which family/config to be created
565  * \param fields fields themselves
566  *
567  * \details
568  * This function is used to create a parameter in realtime configuration space.
569  *
570  * \return Number of rows affected, or -1 on error.
571  *
572  * \note
573  * On the MySQL engine only, for reasons of backwards compatibility, the return
574  * value is the insert ID.  This value is nonportable and may be changed in a
575  * future version to match the other engines.
576  */
577 int ast_store_realtime_fields(const char *family, const struct ast_variable *fields);
578
579 /*!
580  * \brief Create realtime configuration
581  *
582  * \param family which family/config to be created
583  *
584  * \details
585  * This function is used to create a parameter in realtime configuration space.
586  *
587  * \return Number of rows affected, or -1 on error.
588  *
589  * \note
590  * On the MySQL engine only, for reasons of backwards compatibility, the return
591  * value is the insert ID.  This value is nonportable and may be changed in a
592  * future version to match the other engines.
593  *
594  * \note You should use the constant SENTINEL to terminate arguments, in
595  * order to preserve cross-platform compatibility.
596  */
597 int ast_store_realtime(const char *family, ...) attribute_sentinel;
598
599 /*!
600  * \brief Destroy realtime configuration
601  *
602  * \param family which family/config to be destroyed
603  * \param keyfield which field to use as the key
604  * \param lookup which value to look for in the key field to match the entry.
605  * \param fields fields themselves
606  *
607  * \details
608  * This function is used to destroy an entry in realtime configuration space.
609  * Additional params are used as keys.
610  *
611  * \return Number of rows affected, or -1 on error.
612  */
613 int ast_destroy_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
614
615 /*!
616  * \brief Destroy realtime configuration
617  *
618  * \param family which family/config to be destroyed
619  * \param keyfield which field to use as the key
620  * \param lookup which value to look for in the key field to match the entry.
621  *
622  * \details
623  * This function is used to destroy an entry in realtime configuration space.
624  * Additional params are used as keys.
625  *
626  * \return Number of rows affected, or -1 on error.
627  *
628  * \note You should use the constant SENTINEL to terminate arguments, in
629  * order to preserve cross-platform compatibility.
630  */
631 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
632
633 /*!
634  * \brief Check if realtime engine is configured for family
635  * \param family which family/config to be checked
636  * \return 1 if family is configured in realtime and engine exists
637  */
638 int ast_check_realtime(const char *family);
639
640 /*! \brief Check if there's any realtime engines loaded */
641 int ast_realtime_enabled(void);
642
643 /*!
644  * \brief Duplicate variable list
645  * \param var the linked list of variables to clone
646  * \return A duplicated list which you'll need to free with
647  * ast_variables_destroy or NULL when out of memory.
648  *
649  * \note Do not depend on this to copy more than just name, value and filename
650  * (the arguments to ast_variables_new).
651  */
652 struct ast_variable *ast_variables_dup(struct ast_variable *var);
653
654 /*!
655  * \brief Reverse a variable list
656  * \param var the linked list of variables to reverse
657  * \return The head of the reversed variable list
658  *
659  * \note The variable list var is not preserved in this function and should
660  * not be used after reversing it.
661  */
662 struct ast_variable *ast_variables_reverse(struct ast_variable *var);
663
664 /*!
665  * \brief Free variable list
666  * \param var the linked list of variables to free
667  *
668  * \details
669  * This function frees a list of variables.
670  */
671 void ast_variables_destroy(struct ast_variable *var);
672
673 /*!
674  * \brief Register config engine
675  * \retval 1 Always
676  */
677 int ast_config_engine_register(struct ast_config_engine *newconfig);
678
679 /*!
680  * \brief Deregister config engine
681  * \retval 0 Always
682  */
683 int ast_config_engine_deregister(struct ast_config_engine *del);
684
685 /*!
686  * \brief Determine if a mapping exists for a given family
687  *
688  * \param family which family you are looking to see if a mapping exists for
689  * \retval 1 if it is mapped
690  * \retval 0 if it is not
691  */
692 int ast_realtime_is_mapping_defined(const char *family);
693
694 #ifdef TEST_FRAMEWORK
695 /*!
696  * \brief Add an explicit mapping for a family
697  *
698  * \param name Family name
699  * \param driver Driver to use
700  * \param database Database to access
701  * \param table Table to use
702  * \param priority Priority of this mapping
703  */
704 int ast_realtime_append_mapping(const char *name, const char *driver, const char *database, const char *table, int priority);
705 #endif
706
707 /*!
708  * \brief Exposed initialization method for core process
709  *
710  * \details
711  * This method is intended for use only with the core initialization and is
712  * not designed to be called from any user applications.
713  */
714 int register_config_cli(void);
715
716 /*!
717  * \brief Exposed re-initialization method for core process
718  *
719  * \details
720  * This method is intended for use only with the core re-initialization and is
721  * not designed to be called from any user applications.
722  */
723 int read_config_maps(void);
724
725 /*! \brief Create a new base configuration structure */
726 struct ast_config *ast_config_new(void);
727
728 /*!
729  * \brief Retrieve the current category name being built.
730  *
731  * \details
732  * API for backend configuration engines while building a configuration set.
733  */
734 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
735
736 /*!
737  * \brief Set the category within the configuration as being current.
738  *
739  * \details
740  * API for backend configuration engines while building a configuration set.
741  */
742 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
743
744 /*!
745  * \brief Retrieve a configuration variable within the configuration set.
746  *
747  * \details
748  * Retrieves the named variable \p var within category \p cat of configuration
749  * set \p cfg.  If not found, attempts to retrieve the named variable \p var
750  * from within category \em general.
751  *
752  * \return Value of \p var, or NULL if not found.
753  */
754 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
755
756 /*!
757  * \brief Create a category
758  *
759  * \param name name of new category
760  * \param in_file filename which contained the new config
761  * \param lineno line number
762  */
763 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
764
765 /*!
766  * \brief Create a category making it a template
767  *
768  * \param name name of new template
769  * \param in_file filename which contained the new config
770  * \param lineno line number
771  */
772 struct ast_category *ast_category_new_template(const char *name, const char *in_file, int lineno);
773
774 /*!
775  * \brief Inserts new category
776  * 
777  * \param config which config to use
778  * \param cat newly created category to insert
779  * \param match which category to insert above
780  *
781  * \details
782  * This function is used to insert a new category above another category
783  * matching the match parameter.
784  *
785  * \retval 0 if succeeded
786  * \retval -1 if the specified match category wasn't found
787  */
788 int ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
789
790 /*!
791  * \brief Delete a category
792  *
793  * \param config which config to use
794  * \param category category to delete
795  *
796  * \return the category after the deleted one which could be NULL.
797  */
798 struct ast_category *ast_category_delete(struct ast_config *cfg, struct ast_category *category);
799
800 /*!
801  * \brief Appends a category to a config
802  *
803  * \param config which config to use
804  * \param cat category to insert
805  */
806 void ast_category_append(struct ast_config *config, struct ast_category *cat);
807
808 /*!
809  * \brief Applies base (template) to category.
810  *
811  * \param existing existing category
812  * \param base base category
813  *
814  * \details
815  * This function is used to apply a base (template) to an existing category
816  */
817 void ast_category_inherit(struct ast_category *existing, const struct ast_category *base);
818
819 /*!
820  * \brief Removes and destroys all variables in a category
821  *
822  * \param category category to empty
823  *
824  * \retval 0 if succeeded
825  * \retval -1 if categopry is NULL
826  */
827 int ast_category_empty(struct ast_category *category);
828
829 void ast_category_destroy(struct ast_category *cat);
830 struct ast_variable *ast_category_detach_variables(struct ast_category *cat);
831 void ast_category_rename(struct ast_category *cat, const char *name);
832
833 #ifdef MALLOC_DEBUG
834 struct ast_variable *_ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno);
835 #define ast_variable_new(a, b, c) _ast_variable_new(a, b, c, __FILE__, __PRETTY_FUNCTION__, __LINE__)
836 #else
837 struct ast_variable *ast_variable_new(const char *name, const char *value, const char *filename);
838 #endif
839 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);
840 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
841 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
842 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
843 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
844 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
845
846 /*!
847  * \brief Performs an in-place sort on the variable list by ascending name
848  *
849  * \param head The variable list head
850  *
851  * \return The new list head
852  */
853 struct ast_variable *ast_variable_list_sort(struct ast_variable *head);
854
855 /*!
856  * \brief Appends a variable list to the end of another list
857  *
858  * \param head A pointer to an ast_variable * of the existing variable list head. May NOT be NULL
859  * but the content may be to initialize a new list.  If so, upon return, this parameter will be updated
860  * with a pointer to the new list head.
861  * \param search_hint The place in the current list to start searching for the end of the list.
862  * Might help performance on longer lists.  If NULL, it defaults to head.
863  * \param new_var The head of the new variable list to be appended
864  *
865  * \return The tail of the resulting list.
866  *
867  * \note If the existing *head is NULL, it will be updated to new_var.  This allows you to call
868  * ast_variable_list_append in a loop or callback without initializing the list first.
869  */
870 struct ast_variable *ast_variable_list_append_hint(struct ast_variable **head, struct ast_variable *search_hint,
871         struct ast_variable *new_var);
872 #define ast_variable_list_append(head, new_var) ast_variable_list_append_hint(head, NULL, new_var)
873
874 /*!
875  * \brief Update variable value within a config
876  *
877  * \param category Category element within the config
878  * \param variable Name of the variable to change
879  * \param value New value of the variable
880  * \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
881  * \param object Boolean of whether to make the new variable an object
882  *
883  * \return 0 on success or -1 on failure.
884  */
885 int ast_variable_update(struct ast_category *category, const char *variable,
886                                                 const char *value, const char *match, unsigned int object);
887
888 int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
889 int config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator) __attribute__((deprecated));
890
891 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);
892 /*!
893  * \brief
894  * Copies the contents of one ast_config into another
895  *
896  * \note
897  * This creates a config on the heap. The caller of this must
898  * be prepared to free the memory returned.
899  *
900  * \param orig the config to copy
901  * \return The new config on success, NULL on failure.
902  */
903 struct ast_config *ast_config_copy(const struct ast_config *orig);
904
905 /*!
906  * \brief
907  * Flags that affect the behaviour of config hooks.
908  */
909 enum config_hook_flags {
910         butt,
911 };
912
913 /*
914  * \brief Callback when configuration is updated
915  *
916  * \param cfg A copy of the configuration that is being changed.
917  *            This MUST be freed by the callback before returning.
918  */
919 typedef int (*config_hook_cb)(struct ast_config *cfg);
920
921 /*!
922  * \brief
923  * Register a config hook for a particular file and module
924  *
925  * \param name The name of the hook you are registering.
926  * \param filename The file whose config you wish to hook into.
927  * \param module The module that is reloading the config. This
928  *               can be useful if multiple modules may possibly
929  *               reload the same file, but you are only interested
930  *               when a specific module reloads the file
931  * \param flags Flags that affect the way hooks work.
932  * \param hook The callback to be called when config is loaded.
933  * return 0 Success
934  * return -1 Unsuccess, also known as UTTER AND COMPLETE FAILURE
935  */
936 int ast_config_hook_register(const char *name,
937                 const char *filename,
938                 const char *module,
939                 enum config_hook_flags flags,
940                 config_hook_cb hook);
941
942 /*!
943  * \brief
944  * Unregister a config hook
945  *
946  * \param name The name of the hook to unregister
947  */
948 void ast_config_hook_unregister(const char *name);
949
950 /*!
951  * \brief Support code to parse config file arguments
952  *
953  * \details
954  * The function ast_parse_arg() provides a generic interface to parse
955  * strings (e.g. numbers, network addresses and so on) in a flexible
956  * way, e.g. by doing proper error and bound checks, provide default
957  * values, and so on.
958  * The function (described later) takes a string as an argument,
959  * a set of flags to specify the result format and checks to perform,
960  * a pointer to the result, and optionally some additional arguments.
961  *
962  * \return It returns 0 on success, != 0 otherwise.
963  */
964 enum ast_parse_flags {
965         /* low 4 bits of flags are used for the operand type */
966         PARSE_TYPE      =       0x000f,
967         /* numeric types, with optional default value and bound checks.
968          * Additional arguments are passed by value.
969          */
970         PARSE_INT32     =       0x0001,
971         PARSE_UINT32    =       0x0002,
972         PARSE_DOUBLE    =       0x0003,
973 #if 0   /* not supported yet */
974         PARSE_INT16     =       0x0004,
975         PARSE_UINT16    =       0x0005,
976 #endif
977
978         /* Returns a struct ast_sockaddr, with optional default value
979          * (passed by reference) and port handling (accept, ignore,
980          * require, forbid). The format is 'ipaddress[:port]'. IPv6 address
981          * literals need square brackets around them if a port is specified.
982          */
983         PARSE_ADDR      =       0x000e,
984
985         /* Returns a struct sockaddr_in, with optional default value
986          * (passed by reference) and port handling (accept, ignore,
987          * require, forbid). The format is 'host.name[:port]'
988          */
989         PARSE_INADDR    =       0x000f,
990
991         /* Other data types can be added as needed */
992
993         /* If PARSE_DEFAULT is set, next argument is a default value
994          * which is returned in case of error. The argument is passed
995          * by value in case of numeric types, by reference in other cases.
996          */
997         PARSE_DEFAULT   =       0x0010, /* assign default on error */
998
999         /* Request a range check, applicable to numbers. Two additional
1000          * arguments are passed by value, specifying the low-high end of
1001          * the range (inclusive). An error is returned if the value
1002          * is outside or inside the range, respectively.
1003          */
1004         PARSE_IN_RANGE =       0x0020, /* accept values inside a range */
1005         PARSE_OUT_RANGE =      0x0040, /* accept values outside a range */
1006         PARSE_RANGE_DEFAULTS = 0x0080, /* default to range min/max on range error */
1007
1008         /* Port handling, for ast_sockaddr. accept/ignore/require/forbid
1009          * port number after the hostname or address.
1010          */
1011         PARSE_PORT_MASK =       0x0300, /* 0x000: accept port if present */
1012         PARSE_PORT_IGNORE =     0x0100, /* 0x100: ignore port if present */
1013         PARSE_PORT_REQUIRE =    0x0200, /* 0x200: require port number */
1014         PARSE_PORT_FORBID =     0x0300, /* 0x100: forbid port number */
1015 };
1016
1017 /*!
1018  * \brief The argument parsing routine.
1019  *
1020  * \param arg the string to parse. It is not modified.
1021  * \param flags combination of ast_parse_flags to specify the
1022  *      return type and additional checks.
1023  * \param result pointer to the result. NULL is valid here, and can
1024  *      be used to perform only the validity checks.
1025  * \param ... extra arguments are required according to flags.
1026  *
1027  * \retval 0 in case of success, != 0 otherwise.
1028  * \retval result returns the parsed value in case of success,
1029  * the default value in case of error, or it is left unchanged
1030  * in case of error and no default specified. Note that in certain
1031  * cases (e.g. sockaddr_in, with multi-field return values) some
1032  * of the fields in result may be changed even if an error occurs.
1033  *
1034  * \details
1035  * Examples of use:
1036  *     ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE, &a, -1000, 1000);
1037  * returns 0, a = 223
1038  *     ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT, &a, 9999, 10, 100);
1039  * returns 1, a = 9999
1040  *     ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
1041  * returns 1, b unchanged
1042  *    ast_parse_arg("12", PARSE_UINT32|PARSE_IN_RANGE|PARSE_RANGE_DEFAULTS, &a, 1, 10);
1043  * returns 1, a = 10
1044  *    ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
1045  * returns 0, sa contains address and port
1046  *    ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
1047  * returns 1 because port is missing, sa contains address
1048  */
1049 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
1050         void *result, ...);
1051
1052 /*
1053  * Parsing config file options in C is slightly annoying because we cannot use
1054  * string in a switch() statement, yet we need a similar behaviour, with many
1055  * branches and a break on a matching one.
1056  * The following somehow simplifies the job: we create a block using
1057  * the CV_START and CV_END macros, and then within the block we can run
1058  * actions such as "if (condition) { body; break; }"
1059  * Additional macros are present to run simple functions (e.g. ast_copy_string)
1060  * or to pass arguments to ast_parse_arg()
1061  *
1062  * As an example:
1063
1064         CV_START(v->name, v->value);    // start the block
1065         CV_STR("foo", x_foo);           // static string
1066         CV_DSTR("bar", y_bar);          // malloc'ed string
1067         CV_F("bar", ...);               // call a generic function
1068         CV_END;                         // end the block
1069  */
1070
1071 /*! \brief the macro to open a block for variable parsing */
1072 #define CV_START(__in_var, __in_val)            \
1073         do {                                    \
1074                 const char *__var = __in_var;   \
1075                 const char *__val = __in_val;
1076
1077 /*! \brief close a variable parsing block */
1078 #define CV_END                  } while (0)
1079
1080 /*! \brief call a generic function if the name matches. */
1081 #define CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
1082
1083 /*!
1084  * \brief helper macros to assign the value to a BOOL, UINT, static string and
1085  * dynamic string
1086  */
1087 #define CV_BOOL(__x, __dst)     CV_F(__x, (__dst) = ast_true(__val) )
1088 #define CV_UINT(__x, __dst)     CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
1089 #define CV_STR(__x, __dst)      CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
1090 #define CV_DSTR(__x, __dst)     CV_F(__x, ast_free(__dst); __dst = ast_strdup(__val))
1091 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
1092
1093 /*! \brief Check if require type is an integer type */
1094 AST_INLINE_API(
1095 int ast_rq_is_int(require_type type),
1096 {
1097         switch (type) {
1098         case RQ_INTEGER1:
1099         case RQ_UINTEGER1:
1100         case RQ_INTEGER2:
1101         case RQ_UINTEGER2:
1102         case RQ_INTEGER3:
1103         case RQ_UINTEGER3:
1104         case RQ_INTEGER4:
1105         case RQ_UINTEGER4:
1106         case RQ_INTEGER8:
1107         case RQ_UINTEGER8:
1108                 return 1;
1109         default:
1110                 return 0;
1111         }
1112 }
1113 )
1114
1115 /*!
1116  * \brief Remove standard encoding from realtime values, which ensures
1117  * that a semicolon embedded within a single value is not treated upon
1118  * retrieval as multiple values.
1119  * \param chunk Data to be decoded
1120  * \return The decoded data, in the original buffer
1121  * \since 1.8
1122  * \warning This function modifies the original buffer
1123  */
1124 char *ast_realtime_decode_chunk(char *chunk);
1125
1126 /*!
1127  * \brief Encodes a chunk of data for realtime
1128  * \param dest Destination buffer
1129  * \param maxlen Length passed through to ast_str_* functions
1130  * \param chunk Source data to be encoded
1131  * \return Buffer within dest
1132  * \since 1.8
1133  */
1134 char *ast_realtime_encode_chunk(struct ast_str **dest, ssize_t maxlen, const char *chunk);
1135
1136 #if defined(__cplusplus) || defined(c_plusplus)
1137 }
1138 #endif
1139
1140 #endif /* _ASTERISK_CONFIG_H */