Wed Jan 8 2020 09:49:46

Asterisk developer's documentation


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