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