Asterisk - The Open Source Telephony Project  GIT-master-a24979a
include/asterisk/config.h
Go to the documentation of this file.
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 */
42  /*! On a reload, give us a -1 if the file hasn't changed. */
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) */
48 };
49 
50 /*! Flags for ast_config_text_file_save2()
51  */
54  /*! Insure a context doesn't effectively change if a template changes (pre 13.2 behavior) */
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 {
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 */
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 */
131  char *name;
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 cfg 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 *cfg);
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  */
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  */
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  */
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 value from a specific category structure by name
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 the value of a variable from a variable list by name
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 value of 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 Gets a variable from a variable list by name
356  * \since 13.9.0
357  *
358  * \param list variable list to search
359  * \param variable_name name you wish to get the data for
360  *
361  * \details
362  * Goes through a given variable list and searches for the given variable
363  *
364  * \retval The variable (not the value) on success
365  * \retval NULL if unable to find it.
366  */
367 const struct ast_variable *ast_variable_find_variable_in_list(const struct ast_variable *list, const char *variable_name);
368 
369 /*!
370  * \brief Retrieve a category if it exists
371  *
372  * \param config which config to use
373  * \param category_name name of the category you're looking for
374  * \param filter If a config contains more than 1 category with the same name,
375  * you can specify a filter to narrow the search. The filter is a comma-separated
376  * list of <name_regex>=<value_regex> pairs. Only a category with matching
377  * variables will be returned. The special name 'TEMPLATES' can be used with the
378  * special values 'include' or 'restrict' to include templates in the result or
379  * restrict the result to only templates.
380  *
381  * \details
382  * This will search through the categories within a given config file for a match.
383  *
384  * \retval pointer to category if found
385  * \retval NULL if not.
386  */
387 struct ast_category *ast_category_get(const struct ast_config *config,
388  const char *category_name, const char *filter);
389 
390 /*!
391  * \brief Return the name of the category
392  *
393  * \param category category structure
394  *
395  * \retval pointer to category name if found
396  * \retval NULL if not.
397  */
398 const char *ast_category_get_name(const struct ast_category *category);
399 
400 /*!
401  * \brief Check if category is a template
402  *
403  * \param category category structure
404  *
405  * \retval 1 if a template.
406  * \retval 0 if not.
407  */
408 int ast_category_is_template(const struct ast_category *category);
409 
410 /*!
411  * \brief Return the template names this category inherits from
412  *
413  * \param category category structure
414  *
415  * \return an ast_str (which must be freed after use) with a comma
416  * separated list of templates names or NULL if there were no templates.
417  */
418 struct ast_str *ast_category_get_templates(const struct ast_category *category);
419 
420 /*!
421  * \brief Check for category duplicates
422  *
423  * \param config which config to use
424  * \param category_name name of the category you're looking for
425  * \param filter an optional comma-separated list of <name_regex>=<value_regex>
426  * pairs. Only categories with matching variables will be returned.
427  * The special name 'TEMPLATES' can be used with the special values
428  * 'include' or 'restrict' to include templates in the result or
429  * restrict the result to only templates.
430  *
431  * \details
432  * This will search through the categories within a given config file for a match.
433  *
434  * \return non-zero if found
435  */
436 int ast_category_exist(const struct ast_config *config, const char *category_name,
437  const char *filter);
438 
439 /*!
440  * \brief Retrieve realtime configuration
441  *
442  * \param family which family/config to lookup
443  * \param fields which fields to lookup
444  *
445  * \details
446  * This will use builtin configuration backends to look up a particular
447  * entity in realtime and return a variable list of its parameters.
448  *
449  * \note
450  * Unlike the variables in ast_config, the resulting list of variables
451  * MUST be freed with ast_variables_destroy() as there is no container.
452  *
453  * \note
454  * The difference between these two calls is that ast_load_realtime excludes
455  * fields whose values are NULL, while ast_load_realtime_all loads all columns.
456  *
457  * \note
458  * You should use the constant SENTINEL to terminate arguments, in
459  * order to preserve cross-platform compatibility.
460  */
461 struct ast_variable *ast_load_realtime_fields(const char *family, const struct ast_variable *fields);
462 struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
463 struct ast_variable *ast_load_realtime_all_fields(const char *family, const struct ast_variable *fields);
464 struct ast_variable *ast_load_realtime_all(const char *family, ...) attribute_sentinel;
465 
466 /*!
467  * \brief Release any resources cached for a realtime family
468  * \since 1.6.1
469  *
470  * \param family which family/config to destroy
471  *
472  * \details
473  * Various backends may cache attributes about a realtime data storage
474  * facility; on reload, a front end resource may request to purge that cache.
475  *
476  * \retval 0 If any cache was purged
477  * \retval -1 If no cache was found
478  */
479 int ast_unload_realtime(const char *family);
480 
481 /*!
482  * \brief Inform realtime what fields that may be stored
483  * \since 1.6.1
484  *
485  * \param family which family/config is referenced
486  *
487  * \details
488  * This will inform builtin configuration backends that particular fields
489  * may be updated during the use of that configuration section. This is
490  * mainly to be used during startup routines, to ensure that various fields
491  * exist in the backend. The backends may take various actions, such as
492  * creating new fields in the data store or warning the administrator that
493  * new fields may need to be created, in order to ensure proper function.
494  *
495  * The arguments are specified in groups of 3: column name, column type,
496  * and column size. The column types are specified as integer constants,
497  * defined by the enum require_type. Note that the size is specified as
498  * the number of equivalent character fields that a field may take up, even
499  * if a field is otherwise specified as an integer type. This is due to
500  * the fact that some fields have historically been specified as character
501  * types, even if they contained integer values.
502  *
503  * A family should always specify its fields to the minimum necessary
504  * requirements to fulfill all possible values (within reason; for example,
505  * a timeout value may reasonably be specified as an INTEGER2, with size 5.
506  * Even though values above 32767 seconds are possible, they are unlikely
507  * to be useful, and we should not complain about that size).
508  *
509  * \retval 0 Required fields met specified standards
510  * \retval -1 One or more fields was missing or insufficient
511  *
512  * \note You should use the constant SENTINEL to terminate arguments, in
513  * order to preserve cross-platform compatibility.
514  *
515  * TODO The return value of this function is routinely ignored. Ignoring
516  * the return value means that it's mostly pointless to be calling this.
517  * You'll see some warning messages potentially, but that's it.
518  *
519  * XXX This function is super useful for detecting configuration problems
520  * early, but unfortunately, the latest in configuration management, sorcery,
521  * doesn't work well with this. Users of sorcery are familiar with the fields
522  * they will need to write but don't know if realtime is being used. Sorcery
523  * knows what storage mechanism is being used but has no high-level knowledge
524  * of what sort of data is going to be written.
525  */
526 int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
527 
528 /*!
529  * \brief Retrieve realtime configuration
530  *
531  * \param family which family/config to lookup
532  * \param fields list of fields
533  *
534  * \details
535  * This will use builtin configuration backends to look up a particular
536  * entity in realtime and return a variable list of its parameters. Unlike
537  * the ast_load_realtime, this function can return more than one entry and
538  * is thus stored inside a traditional ast_config structure rather than
539  * just returning a linked list of variables.
540  *
541  * \return An ast_config with one or more results
542  * \retval NULL Error or no results returned
543  */
544 struct ast_config *ast_load_realtime_multientry_fields(const char *family, const struct ast_variable *fields);
545 
546 /*!
547  * \brief Retrieve realtime configuration
548  *
549  * \param family which family/config to lookup
550  *
551  * \details
552  * This will use builtin configuration backends to look up a particular
553  * entity in realtime and return a variable list of its parameters. Unlike
554  * the ast_load_realtime, this function can return more than one entry and
555  * is thus stored inside a traditional ast_config structure rather than
556  * just returning a linked list of variables.
557  *
558  * \return An ast_config with one or more results
559  * \retval NULL Error or no results returned
560  *
561  * \note You should use the constant SENTINEL to terminate arguments, in
562  * order to preserve cross-platform compatibility.
563  */
564 struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
565 
566 /*!
567  * \brief Update realtime configuration
568  *
569  * \param family which family/config to be updated
570  * \param keyfield which field to use as the key
571  * \param lookup which value to look for in the key field to match the entry.
572  * \param fields fields to update
573  *
574  * \details
575  * This function is used to update a parameter in realtime configuration space.
576  *
577  * \return Number of rows affected, or -1 on error.
578  */
579 int ast_update_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
580 
581 /*!
582  * \brief Update realtime configuration
583  *
584  * \param family which family/config to be updated
585  * \param keyfield which field to use as the key
586  * \param lookup which value to look for in the key field to match the entry.
587  *
588  * \details
589  * This function is used to update a parameter in realtime configuration space.
590  *
591  * \return Number of rows affected, or -1 on error.
592  *
593  * \note You should use the constant SENTINEL to terminate arguments, in
594  * order to preserve cross-platform compatibility.
595  */
596 int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
597 
598 /*!
599  * \brief Update realtime configuration
600  *
601  * \param family which family/config to be updated
602  * \param lookup_fields fields used to look up entries
603  * \param update_fields fields to update
604  *
605  * \details
606  * This function is used to update a parameter in realtime configuration space.
607  * It includes the ability to lookup a row based upon multiple key criteria.
608  * As a result, this function includes two sentinel values, one to terminate
609  * lookup values and the other to terminate the listing of fields to update.
610  *
611  * \return Number of rows affected, or -1 on error.
612  */
613 int ast_update2_realtime_fields(const char *family, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields);
614 
615 /*!
616  * \brief Update realtime configuration
617  *
618  * \param family which family/config to be updated
619  *
620  * \details
621  * This function is used to update a parameter in realtime configuration space.
622  * It includes the ability to lookup a row based upon multiple key criteria.
623  * As a result, this function includes two sentinel values, one to terminate
624  * lookup values and the other to terminate the listing of fields to update.
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_update2_realtime(const char *family, ...) attribute_sentinel;
632 
633 /*!
634  * \brief Create realtime configuration
635  *
636  * \param family which family/config to be created
637  * \param fields fields themselves
638  *
639  * \details
640  * This function is used to create a parameter in realtime configuration space.
641  *
642  * \return Number of rows affected, or -1 on error.
643  *
644  * \note
645  * On the MySQL engine only, for reasons of backwards compatibility, the return
646  * value is the insert ID. This value is nonportable and may be changed in a
647  * future version to match the other engines.
648  */
649 int ast_store_realtime_fields(const char *family, const struct ast_variable *fields);
650 
651 /*!
652  * \brief Create realtime configuration
653  *
654  * \param family which family/config to be created
655  *
656  * \details
657  * This function is used to create a parameter in realtime configuration space.
658  *
659  * \return Number of rows affected, or -1 on error.
660  *
661  * \note
662  * On the MySQL engine only, for reasons of backwards compatibility, the return
663  * value is the insert ID. This value is nonportable and may be changed in a
664  * future version to match the other engines.
665  *
666  * \note You should use the constant SENTINEL to terminate arguments, in
667  * order to preserve cross-platform compatibility.
668  */
669 int ast_store_realtime(const char *family, ...) attribute_sentinel;
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  * \param fields fields themselves
678  *
679  * \details
680  * This function is used to destroy an entry in realtime configuration space.
681  * Additional params are used as keys.
682  *
683  * \return Number of rows affected, or -1 on error.
684  */
685 int ast_destroy_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields);
686 
687 /*!
688  * \brief Destroy realtime configuration
689  *
690  * \param family which family/config to be destroyed
691  * \param keyfield which field to use as the key
692  * \param lookup which value to look for in the key field to match the entry.
693  *
694  * \details
695  * This function is used to destroy an entry in realtime configuration space.
696  * Additional params are used as keys.
697  *
698  * \return Number of rows affected, or -1 on error.
699  *
700  * \note You should use the constant SENTINEL to terminate arguments, in
701  * order to preserve cross-platform compatibility.
702  */
703 int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
704 
705 /*!
706  * \brief Check if realtime engine is configured for family
707  * \param family which family/config to be checked
708  * \return 1 if family is configured in realtime and engine exists
709  */
710 int ast_check_realtime(const char *family);
711 
712 /*! \brief Check if there's any realtime engines loaded */
713 int ast_realtime_enabled(void);
714 
715 /*!
716  * \brief Duplicate variable list
717  * \param var the linked list of variables to clone
718  * \return A duplicated list which you'll need to free with
719  * ast_variables_destroy or NULL when out of memory.
720  *
721  * \note Do not depend on this to copy more than just name, value and filename
722  * (the arguments to ast_variables_new).
723  */
725 
726 /*!
727  * \brief Reverse a variable list
728  * \param var the linked list of variables to reverse
729  * \return The head of the reversed variable list
730  *
731  * \note The variable list var is not preserved in this function and should
732  * not be used after reversing it.
733  */
735 
736 /*!
737  * \brief Free variable list
738  * \param var the linked list of variables to free
739  *
740  * \details
741  * This function frees a list of variables.
742  */
744 
745 /*!
746  * \brief Register config engine
747  * \retval 1 Always
748  */
749 int ast_config_engine_register(struct ast_config_engine *newconfig);
750 
751 /*!
752  * \brief Deregister config engine
753  * \retval 0 Always
754  */
756 
757 /*!
758  * \brief Determine if a mapping exists for a given family
759  *
760  * \param family which family you are looking to see if a mapping exists for
761  * \retval 1 if it is mapped
762  * \retval 0 if it is not
763  */
764 int ast_realtime_is_mapping_defined(const char *family);
765 
766 #ifdef TEST_FRAMEWORK
767 /*!
768  * \brief Add an explicit mapping for a family
769  *
770  * \param name Family name
771  * \param driver Driver to use
772  * \param database Database to access
773  * \param table Table to use
774  * \param priority Priority of this mapping
775  */
776 int ast_realtime_append_mapping(const char *name, const char *driver, const char *database, const char *table, int priority);
777 #endif
778 
779 /*!
780  * \brief Exposed initialization method for core process
781  *
782  * \details
783  * This method is intended for use only with the core initialization and is
784  * not designed to be called from any user applications.
785  */
786 int register_config_cli(void);
787 
788 /*! \brief Create a new base configuration structure */
789 struct ast_config *ast_config_new(void);
790 
791 /*!
792  * \brief Retrieve the current category name being built.
793  *
794  * \details
795  * API for backend configuration engines while building a configuration set.
796  */
797 struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
798 
799 /*!
800  * \brief Set the category within the configuration as being current.
801  *
802  * \details
803  * API for backend configuration engines while building a configuration set.
804  */
805 void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
806 
807 /*!
808  * \brief Retrieve a configuration variable within the configuration set.
809  *
810  * \details
811  * Retrieves the named variable \p var within category \p cat of configuration
812  * set \p cfg. If not found, attempts to retrieve the named variable \p var
813  * from within category \em general.
814  *
815  * \return Value of \p var, or NULL if not found.
816  */
817 const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
818 
819 /*!
820  * \brief Create a category
821  *
822  * \param name name of new category
823  * \param in_file filename which contained the new config
824  * \param lineno line number
825  */
826 struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
827 
828 /*!
829  * \brief Create a category that is not backed by a file
830  *
831  * \param name name of new category
832  */
833 #define ast_category_new_dynamic(name) ast_category_new(name, "", -1)
834 
835 /*!
836  * \brief Create a nameless category that is not backed by a file
837  */
838 #define ast_category_new_anonymous() ast_category_new_dynamic("")
839 
840 /*!
841  * \brief Create a category making it a template
842  *
843  * \param name name of new template
844  * \param in_file filename which contained the new config
845  * \param lineno line number
846  */
847 struct ast_category *ast_category_new_template(const char *name, const char *in_file, int lineno);
848 
849 /*!
850  * \brief Inserts new category
851  *
852  * \param config which config to use
853  * \param cat newly created category to insert
854  * \param match which category to insert above
855  *
856  * \details
857  * This function is used to insert a new category above another category
858  * matching the match parameter.
859  *
860  * \retval 0 if succeeded
861  * \retval -1 if the specified match category wasn't found
862  */
863 int ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
864 
865 /*!
866  * \brief Delete a category
867  *
868  * \param cfg which config to use
869  * \param cat category to delete
870  *
871  * \return the category after the deleted one which could be NULL.
872  *
873  * \note It is not safe to call ast_category_delete while browsing with
874  * ast_category_browse. It is safe with ast_category_browse_filtered.
875  */
876 struct ast_category *ast_category_delete(struct ast_config *cfg, struct ast_category *cat);
877 
878 /*!
879  * \brief Appends a category to a config
880  *
881  * \param config which config to use
882  * \param category category to insert
883  */
884 void ast_category_append(struct ast_config *config, struct ast_category *category);
885 
886 /*!
887  * \brief Applies base (template) to category.
888  *
889  * \param existing existing category
890  * \param base base category
891  *
892  * \details
893  * This function is used to apply a base (template) to an existing category
894  *
895  * \retval 0 if succeeded
896  * \retval -1 if the memory allocation failed
897  */
898 int ast_category_inherit(struct ast_category *existing, const struct ast_category *base);
899 
900 /*!
901  * \brief Removes and destroys all variables in a category
902  *
903  * \param category category to empty
904  *
905  * \retval 0 if succeeded
906  * \retval -1 if category is NULL
907  */
908 int ast_category_empty(struct ast_category *category);
909 
910 void ast_category_destroy(struct ast_category *cat);
912 void ast_category_rename(struct ast_category *cat, const char *name);
913 
914 struct ast_variable *_ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno);
915 #define ast_variable_new(name, value, filename) _ast_variable_new(name, value, filename, __FILE__, __PRETTY_FUNCTION__, __LINE__)
916 
917 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);
918 struct ast_config_include *ast_include_find(struct ast_config *conf, const char *included_file);
919 void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file);
920 void ast_variable_append(struct ast_category *category, struct ast_variable *variable);
921 void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
922 int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
923 
924 /*!
925  * \brief Performs an in-place sort on the variable list by ascending name
926  *
927  * \param head The variable list head
928  *
929  * \return The new list head
930  */
931 struct ast_variable *ast_variable_list_sort(struct ast_variable *head);
932 
933 /*!
934  * \brief Appends a variable list to the end of another list
935  *
936  * \param head A pointer to an ast_variable * of the existing variable list head. May NOT be NULL
937  * but the content may be to initialize a new list. If so, upon return, this parameter will be updated
938  * with a pointer to the new list head.
939  * \param search_hint The place in the current list to start searching for the end of the list.
940  * Might help performance on longer lists. If NULL, it defaults to head.
941  * \param new_var The head of the new variable list to be appended
942  *
943  * \return The tail of the resulting list.
944  *
945  * \note If the existing *head is NULL, it will be updated to new_var. This allows you to call
946  * ast_variable_list_append in a loop or callback without initializing the list first.
947  */
948 struct ast_variable *ast_variable_list_append_hint(struct ast_variable **head, struct ast_variable *search_hint,
949  struct ast_variable *new_var);
950 #define ast_variable_list_append(head, new_var) ast_variable_list_append_hint(head, NULL, new_var)
951 
952 /*!
953  * \brief Replace a variable in the given list with a new value
954  * \since 13.30.0
955  *
956  * \param head A pointer to an ast_variable * of the existing variable list head. May NOT be NULL
957  * but the content may be to initialize a new list. If so, upon return, this parameter will be updated
958  * with a pointer to the new list head.
959  * \param replacement The variable that replaces another variable in the list with the
960  * same name.
961  *
962  * \retval 0 if a variable was replaced in the list
963  * \retval -1 if no replacement occured
964  *
965  * \note The variable name comparison is performed case-sensitively
966  * \note If a variable is replaced, its memory is freed.
967  */
968 int ast_variable_list_replace(struct ast_variable **head, struct ast_variable *replacement);
969 
970 /*!
971  * \brief Replace a variable in the given list with a new variable
972  *
973  * \param head A pointer to the current variable list head. Since the variable to be
974  * replaced, this pointer may be updated with the new head.
975  * \param oldvar A pointer to the existing variable to be replaced.
976  * \param newvar A pointer to the new variable that will replace the old one.
977  *
978  * \retval 0 if a variable was replaced in the list
979  * \retval -1 if no replacement occured
980  *
981  * \note The search for the old variable is done simply on the pointer.
982  * \note If a variable is replaced, its memory is freed.
983  */
985  struct ast_variable *oldvar,
986  struct ast_variable *newvar);
987 
988 /*!
989  * \brief Join an ast_variable list with specified separators and quoted values
990  *
991  * \param head A pointer to an ast_variable list head.
992  * \param item_separator The string to use to separate the list items.
993  * If NULL, "," will be used.
994  * \param name_value_separator The string to use to separate each item's name and value.
995  * If NULL, "=" will be used.
996  * \param str A pointer to a pre-allocated ast_str in which to put the results.
997  * If NULL, one will be allocated and returned.
998  * \param quote_char The quote char to use for the values.
999  * May be NULL or empty for no quoting.
1000  *
1001  * \retval A pointer to the result ast_str. This may NOT be the same as the pointer
1002  * passed in if the original ast_str wasn't large enough to hold the result.
1003  * Regardless, the pointer MUST be freed after use.
1004  * \retval NULL if there was an error.
1005  */
1006 struct ast_str *ast_variable_list_join(const struct ast_variable *head, const char *item_separator,
1007  const char *name_value_separator, const char *quote_char, struct ast_str **str);
1008 
1009 /*!
1010  * \brief Parse a string into an ast_variable list. The reverse of ast_variable_list_join
1011  *
1012  * \param input The name-value pair string to parse.
1013  * \param item_separator The string used to separate the list items.
1014  * Only the first character in the string will be used.
1015  * If NULL, "," will be used.
1016  * \param name_value_separator The string used to separate each item's name and value.
1017  * Only the first character in the string will be used.
1018  * If NULL, "=" will be used.
1019  *
1020  * \retval A pointer to a list of ast_variables.
1021  * \retval NULL if there was an error or no variables could be parsed.
1022  */
1023 struct ast_variable *ast_variable_list_from_string(const char *input, const char *item_separator,
1024  const char *name_value_separator);
1025 
1026 /*!
1027  * \brief Update variable value within a config
1028  *
1029  * \param category Category element within the config
1030  * \param variable Name of the variable to change
1031  * \param value New value of the variable
1032  * \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
1033  * \param object Boolean of whether to make the new variable an object
1034  *
1035  * \return 0 on success or -1 on failure.
1036  */
1037 int ast_variable_update(struct ast_category *category, const char *variable,
1038  const char *value, const char *match, unsigned int object);
1039 
1040 /*!
1041  * \brief Save a config text file
1042  * \since 13.2.0
1043  *
1044  * \param filename Filename
1045  * \param cfg ast_config
1046  * \param generator generator
1047  * \param flags List of config_save_flags
1048  *
1049  * \retval 0 on success.
1050  * \retval -1 on failure.
1051  */
1052 int ast_config_text_file_save2(const char *filename, const struct ast_config *cfg, const char *generator, uint32_t flags);
1053 
1054 /*!
1055  * \brief Save a config text file preserving the pre 13.2 behavior
1056  *
1057  * \param filename Filename
1058  * \param cfg ast_config
1059  * \param generator generator
1060  *
1061  * \retval 0 on success.
1062  * \retval -1 on failure.
1063  */
1064 int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator);
1065 
1066 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);
1067 /*!
1068  * \brief
1069  * Copies the contents of one ast_config into another
1070  *
1071  * \note
1072  * This creates a config on the heap. The caller of this must
1073  * be prepared to free the memory returned.
1074  *
1075  * \param orig the config to copy
1076  * \return The new config on success, NULL on failure.
1077  */
1078 struct ast_config *ast_config_copy(const struct ast_config *orig);
1079 
1080 /*!
1081  * \brief
1082  * Flags that affect the behaviour of config hooks.
1083  */
1086 };
1087 
1088 /*!
1089  * \brief Callback when configuration is updated
1090  *
1091  * \param cfg A copy of the configuration that is being changed.
1092  * This MUST be freed by the callback before returning.
1093  */
1094 typedef int (*config_hook_cb)(struct ast_config *cfg);
1095 
1096 /*!
1097  * \brief
1098  * Register a config hook for a particular file and module
1099  *
1100  * \param name The name of the hook you are registering.
1101  * \param filename The file whose config you wish to hook into.
1102  * \param module The module that is reloading the config. This
1103  * can be useful if multiple modules may possibly
1104  * reload the same file, but you are only interested
1105  * when a specific module reloads the file
1106  * \param flags Flags that affect the way hooks work.
1107  * \param hook The callback to be called when config is loaded.
1108  * return 0 Success
1109  * return -1 Unsuccess, also known as UTTER AND COMPLETE FAILURE
1110  */
1111 int ast_config_hook_register(const char *name,
1112  const char *filename,
1113  const char *module,
1114  enum config_hook_flags flags,
1115  config_hook_cb hook);
1116 
1117 /*!
1118  * \brief
1119  * Unregister a config hook
1120  *
1121  * \param name The name of the hook to unregister
1122  */
1123 void ast_config_hook_unregister(const char *name);
1124 
1125 /*!
1126  * \brief Support code to parse config file arguments
1127  *
1128  * \details
1129  * The function ast_parse_arg() provides a generic interface to parse
1130  * strings (e.g. numbers, network addresses and so on) in a flexible
1131  * way, e.g. by doing proper error and bound checks, provide default
1132  * values, and so on.
1133  * The function (described later) takes a string as an argument,
1134  * a set of flags to specify the result format and checks to perform,
1135  * a pointer to the result, and optionally some additional arguments.
1136  *
1137  * \return 0 on success, != 0 otherwise.
1138  */
1140  /* low 4 bits of flags are used for the operand type */
1141  PARSE_TYPE = 0x000f,
1142  /* numeric types, with optional default value and bound checks.
1143  * Additional arguments are passed by value.
1144  */
1145  PARSE_INT32 = 0x0001,
1146  PARSE_UINT32 = 0x0002,
1147  PARSE_DOUBLE = 0x0003,
1148 #if 0 /* not supported yet */
1149  PARSE_INT16 = 0x0004,
1150  PARSE_UINT16 = 0x0005,
1151 #endif
1152 
1153  /* Returns an int processed by ast_app_parse_timelen.
1154  * The first argument is an enum ast_timelen value (required).
1155  */
1156  PARSE_TIMELEN = 0x0006,
1157 
1158  /* Returns a struct ast_sockaddr, with optional default value
1159  * (passed by reference) and port handling (accept, ignore,
1160  * require, forbid). The format is 'ipaddress[:port]'. IPv6 address
1161  * literals need square brackets around them if a port is specified.
1162  */
1163  PARSE_ADDR = 0x000e,
1164 
1165  /* Returns a struct sockaddr_in, with optional default value
1166  * (passed by reference) and port handling (accept, ignore,
1167  * require, forbid). The format is 'host.name[:port]'
1168  */
1169  PARSE_INADDR = 0x000f,
1170 
1171  /* Other data types can be added as needed */
1172 
1173  /* If PARSE_DEFAULT is set, next argument is a default value
1174  * which is returned in case of error. The argument is passed
1175  * by value in case of numeric types, by reference in other cases.
1176  */
1177  PARSE_DEFAULT = 0x0010, /* assign default on error */
1178 
1179  /* Request a range check, applicable to numbers. Two additional
1180  * arguments are passed by value, specifying the low-high end of
1181  * the range (inclusive). An error is returned if the value
1182  * is outside or inside the range, respectively.
1183  */
1184  PARSE_IN_RANGE = 0x0020, /* accept values inside a range */
1185  PARSE_OUT_RANGE = 0x0040, /* accept values outside a range */
1186  PARSE_RANGE_DEFAULTS = 0x0080, /* default to range min/max on range error */
1187 
1188  /* Port handling, for ast_sockaddr. accept/ignore/require/forbid
1189  * port number after the hostname or address.
1190  */
1191  PARSE_PORT_MASK = 0x0300, /* 0x000: accept port if present */
1192  PARSE_PORT_IGNORE = 0x0100, /* 0x100: ignore port if present */
1193  PARSE_PORT_REQUIRE = 0x0200, /* 0x200: require port number */
1194  PARSE_PORT_FORBID = 0x0300, /* 0x100: forbid port number */
1195 };
1196 
1197 /*!
1198  * \brief The argument parsing routine.
1199  *
1200  * \param arg the string to parse. It is not modified.
1201  * \param flags combination of ast_parse_flags to specify the
1202  * return type and additional checks.
1203  * \param p_result pointer to the result. NULL is valid here, and can
1204  * be used to perform only the validity checks.
1205  * \param ... extra arguments are required according to flags.
1206  *
1207  * \retval 0 in case of success, != 0 otherwise.
1208  * \retval result returns the parsed value in case of success,
1209  * the default value in case of error, or it is left unchanged
1210  * in case of error and no default specified. Note that in certain
1211  * cases (e.g. sockaddr_in, with multi-field return values) some
1212  * of the fields in result may be changed even if an error occurs.
1213  *
1214  * \details
1215  * Examples of use:
1216  * ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE, &a, -1000, 1000);
1217  * returns 0, a = 223
1218  * ast_parse_arg("22345", PARSE_INT32|PARSE_IN_RANGE|PARSE_DEFAULT, &a, 9999, 10, 100);
1219  * returns 1, a = 9999
1220  * ast_parse_arg("22345ssf", PARSE_UINT32|PARSE_IN_RANGE, &b, 10, 100);
1221  * returns 1, b unchanged
1222  * ast_parse_arg("12", PARSE_UINT32|PARSE_IN_RANGE|PARSE_RANGE_DEFAULTS, &a, 1, 10);
1223  * returns 1, a = 10
1224  * ast_parse_arg("223", PARSE_TIMELEN|PARSE_IN_RANGE, &a, TIMELEN_SECONDS, -1000, 1000);
1225  * returns 0, a = 1000
1226  * ast_parse_arg("223", PARSE_TIMELEN|PARSE_IN_RANGE, &a, TIMELEN_SECONDS, -1000, 250000);
1227  * returns 0, a = 223000
1228  * ast_parse_arg("223", PARSE_TIMELEN|PARSE_IN_RANGE|PARSE_DEFAULT, &a, TIMELEN_SECONDS, 9999, -1000, 250000);
1229  * returns 0, a = 9999
1230  * ast_parse_arg("www.foo.biz:44", PARSE_INADDR, &sa);
1231  * returns 0, sa contains address and port
1232  * ast_parse_arg("www.foo.biz", PARSE_INADDR|PARSE_PORT_REQUIRE, &sa);
1233  * returns 1 because port is missing, sa contains address
1234  */
1235 int ast_parse_arg(const char *arg, enum ast_parse_flags flags,
1236  void *p_result, ...);
1237 
1238 /*
1239  * Parsing config file options in C is slightly annoying because we cannot use
1240  * string in a switch() statement, yet we need a similar behaviour, with many
1241  * branches and a break on a matching one.
1242  * The following somehow simplifies the job: we create a block using
1243  * the CV_START and CV_END macros, and then within the block we can run
1244  * actions such as "if (condition) { body; break; }"
1245  * Additional macros are present to run simple functions (e.g. ast_copy_string)
1246  * or to pass arguments to ast_parse_arg()
1247  *
1248  * As an example:
1249 
1250  CV_START(v->name, v->value); // start the block
1251  CV_STR("foo", x_foo); // static string
1252  CV_DSTR("bar", y_bar); // malloc'ed string
1253  CV_F("bar", ...); // call a generic function
1254  CV_END; // end the block
1255  */
1256 
1257 /*! \brief the macro to open a block for variable parsing */
1258 #define CV_START(__in_var, __in_val) \
1259  do { \
1260  const char *__var = __in_var; \
1261  const char *__val = __in_val;
1262 
1263 /*! \brief close a variable parsing block */
1264 #define CV_END } while (0)
1265 
1266 /*! \brief call a generic function if the name matches. */
1267 #define CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
1268 
1269 /*!
1270  * \brief helper macros to assign the value to a BOOL, UINT, static string and
1271  * dynamic string
1272  */
1273 #define CV_BOOL(__x, __dst) CV_F(__x, (__dst) = ast_true(__val) )
1274 #define CV_UINT(__x, __dst) CV_F(__x, (__dst) = strtoul(__val, NULL, 0) )
1275 #define CV_STR(__x, __dst) CV_F(__x, ast_copy_string(__dst, __val, sizeof(__dst)))
1276 #define CV_DSTR(__x, __dst) CV_F(__x, ast_free(__dst); __dst = ast_strdup(__val))
1277 #define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
1278 
1279 /*! \brief Check if require type is an integer type */
1282 {
1283  switch (type) {
1284  case RQ_INTEGER1:
1285  case RQ_UINTEGER1:
1286  case RQ_INTEGER2:
1287  case RQ_UINTEGER2:
1288  case RQ_INTEGER3:
1289  case RQ_UINTEGER3:
1290  case RQ_INTEGER4:
1291  case RQ_UINTEGER4:
1292  case RQ_INTEGER8:
1293  case RQ_UINTEGER8:
1294  return 1;
1295  default:
1296  return 0;
1297  }
1298 }
1300 
1301 /*!
1302  * \brief Remove standard encoding from realtime values, which ensures
1303  * that a semicolon embedded within a single value is not treated upon
1304  * retrieval as multiple values.
1305  * \param chunk Data to be decoded
1306  * \return The decoded data, in the original buffer
1307  * \since 1.8
1308  * \warning This function modifies the original buffer
1309  */
1310 char *ast_realtime_decode_chunk(char *chunk);
1311 
1312 /*!
1313  * \brief Encodes a chunk of data for realtime
1314  * \param dest Destination buffer
1315  * \param maxlen Length passed through to ast_str_* functions
1316  * \param chunk Source data to be encoded
1317  * \return Buffer within dest
1318  * \since 1.8
1319  */
1320 char *ast_realtime_encode_chunk(struct ast_str **dest, ssize_t maxlen, const char *chunk);
1321 
1322 /*!
1323  * \brief Tests 2 variable values to see if they match
1324  * \since 13.9.0
1325  *
1326  * \param left Variable to test
1327  * \param right Variable to match against with an optional realtime-style operator in the name
1328  *
1329  * \retval 1 matches
1330  * \retval 0 doesn't match
1331  *
1332  * \details
1333  *
1334  * The values of the variables are passed to ast_strings_match.
1335  * If right->name is suffixed with a space and an operator, that operator
1336  * is also passed to ast_strings_match.
1337  *
1338  * Examples:
1339  *
1340  * left->name = "id" (ignored)
1341  * left->value = "abc"
1342  * right->name = "id regex" (id is ignored)
1343  * right->value = "a[bdef]c"
1344  *
1345  * will result in ast_strings_match("abc", "regex", "a[bdef]c") which will return 1.
1346  *
1347  * left->name = "id" (ignored)
1348  * left->value = "abc"
1349  * right->name = "id" (ignored)
1350  * right->value = "abc"
1351  *
1352  * will result in ast_strings_match("abc", NULL, "abc") which will return 1.
1353  *
1354  * See the documentation for ast_strings_match for the valid operators.
1355  */
1356 int ast_variables_match(const struct ast_variable *left, const struct ast_variable *right);
1357 
1358 /*!
1359  * \brief Tests 2 variable lists to see if they match
1360  * \since 13.9.0
1361  *
1362  * \param left Variable list to test
1363  * \param right Variable list with an optional realtime-style operator in the names
1364  * \param exact_match If true, all variables in left must match all variables in right
1365  * and vice versa. This does exact value matches only. Operators aren't supported.
1366  * Except for order, the left and right lists must be equal.
1367  *
1368  * If false, every variable in the right list must match some variable in the left list
1369  * using the operators supplied. Variables in the left list that aren't in the right
1370  * list are ignored for matching purposes.
1371  *
1372  * \retval 1 matches
1373  * \retval 0 doesn't match
1374  *
1375  * \details
1376  * Iterates over the variable lists calling ast_variables_match. If any match fails
1377  * or a variable in the right list isn't in the left list, 0 is returned.
1378  */
1379 int ast_variable_lists_match(const struct ast_variable *left, const struct ast_variable *right,
1380  int exact_match);
1381 
1382 #if defined(__cplusplus) || defined(c_plusplus)
1383 }
1384 #endif
1385 
1386 #endif /* _ASTERISK_CONFIG_H */
const char * str
Definition: app_jack.c:147
#define var
Definition: ast_expr2f.c:614
static int input(yyscan_t yyscanner)
Definition: ast_expr2f.c:1584
static int priority
static char * table
Definition: cdr_odbc.c:55
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2312
static const char type[]
Definition: chan_ooh323.c:109
static const char config[]
Definition: chan_ooh323.c:111
#define attribute_sentinel
Definition: compiler.h:65
static const char name[]
Definition: format_mp3.c:68
static int filter(struct ast_channel *chan, const char *cmd, char *parse, char *buf, size_t len)
Definition: func_strings.c:734
void ast_include_rename(struct ast_config *conf, const char *from_file, const char *to_file)
Definition: main/config.c:383
struct ast_variable * realtime_var_get(const char *database, const char *table, const struct ast_variable *fields)
int ast_category_inherit(struct ast_category *existing, const struct ast_category *base)
Applies base (template) to category.
Definition: main/config.c:1441
const char * ast_variable_retrieve_filtered(struct ast_config *config, const char *category, const char *variable, const char *filter)
Gets a variable by context and variable names.
Definition: main/config.c:793
const char * ast_variable_find_in_list(const struct ast_variable *list, const char *variable)
Gets the value of a variable from a variable list by name.
Definition: main/config.c:904
int realtime_require(const char *database, const char *table, va_list ap)
Function pointer called to ensure database schema is properly configured for realtime use.
struct ast_variable * ast_load_realtime(const char *family,...) attribute_sentinel
Definition: main/config.c:3405
const char * ast_category_get_name(const struct ast_category *category)
Return the name of the category.
Definition: main/config.c:1102
struct ast_variable * ast_category_detach_variables(struct ast_category *cat)
Definition: main/config.c:1425
char * ast_category_browse(struct ast_config *config, const char *prev_name)
Browse categories.
Definition: extconf.c:3327
int ast_variables_match(const struct ast_variable *left, const struct ast_variable *right)
Tests 2 variable values to see if they match.
Definition: main/config.c:826
int ast_store_realtime_fields(const char *family, const struct ast_variable *fields)
Create realtime configuration.
Definition: main/config.c:3618
struct ast_variable * ast_variables_reverse(struct ast_variable *var)
Reverse a variable list.
Definition: main/config.c:565
int ast_config_text_file_save2(const char *filename, const struct ast_config *cfg, const char *generator, uint32_t flags)
Save a config text file.
Definition: main/config.c:2621
struct ast_category * ast_category_browse_filtered(struct ast_config *config, const char *category_name, struct ast_category *prev, const char *filter)
Browse categories with filters.
Definition: main/config.c:1409
struct ast_variable * ast_load_realtime_all(const char *family,...) attribute_sentinel
Definition: main/config.c:3353
int realtime_unload(const char *database, const char *table)
Function pointer called to clear the database cache and free resources used for such.
struct ast_config * ast_load_realtime_multientry(const char *family,...) attribute_sentinel
Retrieve realtime configuration.
Definition: main/config.c:3521
void ast_category_rename(struct ast_category *cat, const char *name)
Definition: main/config.c:1436
void ast_config_sort_categories(struct ast_config *config, int descending, int(*comparator)(struct ast_category *p, struct ast_category *q))
Sorts categories in a config in the order of a numerical value contained within them.
Definition: main/config.c:1245
int ast_update2_realtime(const char *family,...) attribute_sentinel
Update realtime configuration.
Definition: main/config.c:3594
int ast_destroy_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields)
Destroy realtime configuration.
Definition: main/config.c:3655
struct ast_config * ast_config_copy(const struct ast_config *orig)
Copies the contents of one ast_config into another.
Definition: main/config.c:3145
int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line)
Definition: main/config.c:1473
struct ast_variable * ast_category_first(struct ast_category *cat)
given a pointer to a category, return the root variable.
Definition: main/config.c:1231
struct ast_config * ast_config_new(void)
Create a new base configuration structure.
Definition: extconf.c:3275
struct ast_variable * ast_category_root(struct ast_config *config, char *cat)
returns the root ast_variable of a config
Definition: main/config.c:1236
void ast_config_hook_unregister(const char *name)
Unregister a config hook.
Definition: main/config.c:4173
int ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match)
Inserts new category.
Definition: main/config.c:1157
int ast_realtime_require_field(const char *family,...) attribute_sentinel
Inform realtime what fields that may be stored.
Definition: main/config.c:3448
int ast_config_text_file_save(const char *filename, const struct ast_config *cfg, const char *generator)
Save a config text file preserving the pre 13.2 behavior.
Definition: main/config.c:2597
struct ast_config * ast_load_realtime_multientry_fields(const char *family, const struct ast_variable *fields)
Retrieve realtime configuration.
Definition: main/config.c:3495
void ast_category_append(struct ast_config *config, struct ast_category *category)
Appends a category to a config.
Definition: extconf.c:2834
struct ast_str * ast_variable_list_join(const struct ast_variable *head, const char *item_separator, const char *name_value_separator, const char *quote_char, struct ast_str **str)
Join an ast_variable list with specified separators and quoted values.
Definition: main/config.c:699
struct ast_str * ast_category_get_templates(const struct ast_category *category)
Return the template names this category inherits from.
Definition: main/config.c:1112
void ast_variable_append(struct ast_category *category, struct ast_variable *variable)
Definition: extconf.c:1177
struct ast_variable * ast_variable_browse_filtered(const struct ast_config *config, const char *category_name, const char *filter)
Browse variables.
struct ast_variable * ast_variables_dup(struct ast_variable *var)
Duplicate variable list.
Definition: main/config.c:543
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)
int ast_variable_update(struct ast_category *category, const char *variable, const char *value, const char *match, unsigned int object)
Update variable value within a config.
Definition: main/config.c:1518
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)
Definition: extconf.c:1074
const char * ast_variable_find_last_in_list(const struct ast_variable *list, const char *variable)
Gets the value of the LAST occurrence of a variable from a variable list.
Definition: main/config.c:916
int ast_realtime_enabled(void)
Check if there's any realtime engines loaded.
Definition: main/config.c:3443
struct ast_category * ast_category_new(const char *name, const char *in_file, int lineno)
Create a category.
Definition: extconf.c:2789
int ast_unload_realtime(const char *family)
Release any resources cached for a realtime family.
Definition: main/config.c:3475
int ast_config_engine_deregister(struct ast_config_engine *del)
Deregister config engine.
Definition: main/config.c:3072
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)
Definition: main/config.c:3178
void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat)
Set the category within the configuration as being current.
Definition: extconf.c:3363
int ast_variable_list_replace_variable(struct ast_variable **head, struct ast_variable *oldvar, struct ast_variable *newvar)
Replace a variable in the given list with a new variable.
Definition: main/config.c:682
int ast_realtime_is_mapping_defined(const char *family)
Determine if a mapping exists for a given family.
Definition: main/config.c:3092
struct ast_category * ast_category_delete(struct ast_config *cfg, struct ast_category *cat)
Delete a category.
Definition: main/config.c:1552
struct ast_category * ast_config_get_current_category(const struct ast_config *cfg)
Retrieve the current category name being built.
Definition: extconf.c:2782
@ CONFIG_FLAG_NOCACHE
@ CONFIG_FLAG_NOREALTIME
@ CONFIG_FLAG_WITHCOMMENTS
@ CONFIG_FLAG_FILEUNCHANGED
@ CONFIG_SAVE_FLAG_NONE
@ CONFIG_SAVE_FLAG_PRESERVE_EFFECTIVE_CONTEXT
struct ast_variable * ast_variable_list_from_string(const char *input, const char *item_separator, const char *name_value_separator)
Parse a string into an ast_variable list. The reverse of ast_variable_list_join.
Definition: main/config.c:725
int ast_parse_arg(const char *arg, enum ast_parse_flags flags, void *p_result,...)
The argument parsing routine.
Definition: main/config.c:3726
int ast_check_realtime(const char *family)
Check if realtime engine is configured for family.
Definition: main/config.c:3429
int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup,...) attribute_sentinel
Destroy realtime configuration.
Definition: main/config.c:3675
void ast_category_destroy(struct ast_category *cat)
Definition: extconf.c:2846
struct ast_category * ast_category_get(const struct ast_config *config, const char *category_name, const char *filter)
Retrieve a category if it exists.
Definition: main/config.c:1096
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
struct ast_variable * ast_load_realtime_fields(const char *family, const struct ast_variable *fields)
Retrieve realtime configuration.
Definition: main/config.c:3370
const char * ast_variable_retrieve(struct ast_config *config, const char *category, const char *variable)
Definition: main/config.c:768
int ast_category_empty(struct ast_category *category)
Removes and destroys all variables in a category.
Definition: main/config.c:1584
int ast_category_is_template(const struct ast_category *category)
Check if category is a template.
Definition: main/config.c:1107
struct ast_config * ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags)
Load a config file.
Definition: main/config.c:3220
struct ast_category * ast_category_new_template(const char *name, const char *in_file, int lineno)
Create a category making it a template.
Definition: main/config.c:1069
struct ast_config_include * ast_include_find(struct ast_config *conf, const char *included_file)
Definition: extconf.c:1163
int ast_variable_list_replace(struct ast_variable **head, struct ast_variable *replacement)
Replace a variable in the given list with a new value.
Definition: main/config.c:666
int ast_rq_is_int(require_type type)
Check if require type is an integer type.
char * ast_realtime_decode_chunk(char *chunk)
Remove standard encoding from realtime values, which ensures that a semicolon embedded within a singl...
Definition: main/config.c:3694
int ast_update_realtime(const char *family, const char *keyfield, const char *lookup,...) attribute_sentinel
Update realtime configuration.
Definition: main/config.c:3558
int ast_update_realtime_fields(const char *family, const char *keyfield, const char *lookup, const struct ast_variable *fields)
Update realtime configuration.
Definition: main/config.c:3537
struct ast_variable * ast_variable_list_append_hint(struct ast_variable **head, struct ast_variable *search_hint, struct ast_variable *new_var)
Appends a variable list to the end of another list.
Definition: main/config.c:646
require_type
Types used in ast_realtime_require_field.
int ast_store_realtime(const char *family,...) attribute_sentinel
Create realtime configuration.
Definition: main/config.c:3639
struct ast_variable * _ast_variable_new(const char *name, const char *value, const char *filename, const char *file, const char *function, int lineno)
Definition: main/config.c:288
int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields)
struct ast_config * realtime_multi_get(const char *database, const char *table, const struct ast_variable *fields)
struct ast_variable * ast_variable_list_sort(struct ast_variable *head)
Performs an in-place sort on the variable list by ascending name.
Definition: main/config.c:620
int realtime_update2(const char *database, const char *table, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields)
int ast_category_exist(const struct ast_config *config, const char *category_name, const char *filter)
Check for category duplicates.
Definition: main/config.c:1135
void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line)
Definition: main/config.c:499
int ast_variable_lists_match(const struct ast_variable *left, const struct ast_variable *right, int exact_match)
Tests 2 variable lists to see if they match.
Definition: main/config.c:846
struct ast_variable * ast_load_realtime_all_fields(const char *family, const struct ast_variable *fields)
Definition: main/config.c:3332
ast_parse_flags
Support code to parse config file arguments.
@ PARSE_RANGE_DEFAULTS
@ PARSE_PORT_REQUIRE
const char * ast_config_option(struct ast_config *cfg, const char *cat, const char *var)
Retrieve a configuration variable within the configuration set.
Definition: main/config.c:758
int ast_config_hook_register(const char *name, const char *filename, const char *module, enum config_hook_flags flags, config_hook_cb hook)
Register a config hook for a particular file and module.
Definition: main/config.c:4201
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
char * ast_realtime_encode_chunk(struct ast_str **dest, ssize_t maxlen, const char *chunk)
Encodes a chunk of data for realtime.
Definition: main/config.c:3706
int(* config_hook_cb)(struct ast_config *cfg)
Callback when configuration is updated.
int realtime_destroy(const char *database, const char *table, const char *keyfield, const char *entity, const struct ast_variable *fields)
int ast_update2_realtime_fields(const char *family, const struct ast_variable *lookup_fields, const struct ast_variable *update_fields)
Update realtime configuration.
Definition: main/config.c:3574
config_hook_flags
Flags that affect the behaviour of config hooks.
struct ast_variable * ast_variable_browse(const struct ast_config *config, const char *category_name)
Definition: extconf.c:1215
int ast_config_engine_register(struct ast_config_engine *newconfig)
Register config engine.
Definition: main/config.c:3056
int realtime_store(const char *database, const char *table, const struct ast_variable *fields)
const char * ast_variable_find(const struct ast_category *category, const char *variable)
Gets a variable value from a specific category structure by name.
Definition: main/config.c:809
const struct ast_variable * ast_variable_find_variable_in_list(const struct ast_variable *list, const char *variable_name)
Gets a variable from a variable list by name.
Definition: main/config.c:814
int register_config_cli(void)
Exposed initialization method for core process.
Definition: main/config.c:4135
Inlinable API function macro.
#define AST_INLINE_API(hdr, body)
Definition: inline_api.h:54
static int ast_realtime_append_mapping(const char *name, const char *driver, const char *database, const char *table, int priority)
Definition: main/config.c:2936
struct ast_category * prev
Definition: main/config.c:244
Structure to keep comments for rewriting configuration files.
Definition: main/config.c:84
Configuration engine structure, used to define realtime drivers.
realtime_var_get * realtime_func
struct ast_config_engine * next
realtime_destroy * destroy_func
realtime_unload * unload_func
realtime_store * store_func
realtime_multi_get * realtime_multi_func
config_load_func * load_func
realtime_update * update_func
realtime_update2 * update2_func
realtime_require * require_func
char * exec_file
if it's an exec, you'll have both the /var/tmp to read, and the original script
Definition: main/config.c:273
char * included_file
file name included
Definition: main/config.c:278
Structure used to handle boolean flags.
Definition: utils.h:199
Support for dynamic strings.
Definition: strings.h:604
Structure for variables, used for configurations and for channel variables.
char stuff[0]
Contents of file, name, and value in that order stuffed here.
struct ast_comment * precomments
struct ast_comment * trailing
struct ast_comment * sameline
struct ast_variable * next
All configuration options for statsd client.
Definition: res_statsd.c:101
int value
Definition: syslog.c:37
Utility functions.