Asterisk - The Open Source Telephony Project  GIT-master-8beac82
config_options.h
Go to the documentation of this file.
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2012, 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 option-handling
21  * \author Terry Wilson <twilson@digium.com>
22  */
23 
24 #ifndef _ASTERISK_CONFIG_OPTIONS_H
25 #define _ASTERISK_CONFIG_OPTIONS_H
26 
27 #if defined(__cplusplus) || defined(c_plusplus)
28 extern "C" {
29 #endif
30 
31 #include <regex.h>
32 
33 #include "asterisk/config.h"
34 #include "asterisk/astobj2.h"
35 
36 struct aco_option;
37 struct aco_info_internal;
38 struct aco_type_internal;
39 
40 enum aco_type_t {
44 };
45 
46 /*! Type of category matching to perform */
48  /*! Regex based blacklist. */
50  /*! Regex based whitelist. */
52  /*! Blacklist with a single string matched with strcasecmp. */
54  /*! Whitelist with a single string matched with strcasecmp. */
56  /*! Blacklist with a NULL terminated array of strings matched with strcasecmp. */
58  /*! Whitelist with a NULL terminated array of strings matched with strcasecmp. */
60 };
61 
62 /*! \brief What kind of matching should be done on an option name */
64  ACO_EXACT = 1,
67 };
68 
69 /*! Callback functions for option parsing via aco_process_config() */
70 
71 /*! \brief Allocate a configurable ao2 object
72  * \param category The config category the object is being generated for
73  * \retval NULL error
74  * \retval non-NULL a new configurable ao2 object
75  */
76 typedef void *(*aco_type_item_alloc)(const char *category);
77 
78 /*! \brief Find a item given a category and container of items
79  * \param container The container to search for the item
80  * \param category The category associated with the item
81  * \retval non-NULL item from the container
82  * \retval NULL item does not exist in container
83  */
84 typedef void *(*aco_type_item_find)(struct ao2_container *newcontainer, const char *category);
85 
86 /*! \brief Callback function that is called after a config object is initialized with defaults
87  *
88  * \note This callback is called during config processing after a new config is allocated and
89  * and defaults applied but before values from the config are read. This callback could be used
90  * to merge in settings inherited from the global settings if necessary, despite that being a
91  * bad thing to do!
92  *
93  * \param newitem The newly allocated config object with defaults populated
94  * \retval 0 succes, continue processing
95  * \retval non-zero failure, stop processing
96  */
97 typedef int (*aco_type_item_pre_process)(void *newitem);
98 
99 /*! \brief Callback function that is called after config processing, but before linking
100  *
101  * \note This callback is called after config processing, but before linking the object
102  * in the config container. This callback can be used to verify that all settings make
103  * sense together, that required options have been set, etc.
104  *
105  * \param newitem The newly configured object
106  * \retval 0 success, continue processing
107  * \retval non-zero failure, stop processing
108  */
109 typedef int (*aco_type_prelink)(void *newitem);
110 
111 /*! \brief A function for determining whether the value for the matchfield in an aco_type is sufficient for a match
112  * \param text The value of the option
113  * \retval -1 The value is sufficient for a match
114  * \retval 0 The value is not sufficient for a match
115  */
116 typedef int (*aco_matchvalue_func)(const char *text);
117 
118 /*! \struct aco_type
119  * \brief Type information about a category-level configurable object
120  */
121 struct aco_type {
122  /* common stuff */
123  enum aco_type_t type; /*!< Whether this is a global or item type */
124  const char *name; /*!< The name of this type (must match XML documentation) */
125  const char *category; /*!< A regular expression for matching categories to be allowed or denied */
126  const char *matchfield; /*!< An option name to match for this type (i.e. a 'type'-like column) */
127  const char *matchvalue; /*!< The value of the option to require for matching (i.e. 'peer' for type= in sip.conf) */
128  aco_matchvalue_func matchfunc; /*!< A function for determing whether the option value matches (i.e. hassip= requires ast_true()) */
129  enum aco_category_op category_match; /*!< Whether the following category regex is a whitelist or blacklist */
130  size_t item_offset; /*!< The offset in the config snapshot for the global config or item config container */
131  unsigned int hidden; /*!< Type is for internal purposes only and it and all options should not be visible to users */
132 
133  /* non-global callbacks */
134  aco_type_item_alloc item_alloc; /*!< An allocation function for item associated with this type */
135  aco_type_item_find item_find; /*!< A callback function to find an existing item in a particular container */
136  aco_type_item_pre_process item_pre_process; /*!< An optional callback function that is called after defaults are applied, but before config processing */
137  aco_type_prelink item_prelink; /*!< An optional callback function that is called after config processing, but before applying changes */
138  struct aco_type_internal *internal;
139 };
140 
141 /*! \brief A callback function to run just prior to applying config changes
142  * \retval 0 Success
143  * \retval non-zero Failure. Changes not applied
144  */
145 typedef int (*aco_pre_apply_config)(void);
146 
147 /*! \brief A callback function called only if config changes have been applied
148  *
149  * \note If a config file has not been edited prior to performing a reload, this
150  * callback will not be called.
151  */
152 typedef void (*aco_post_apply_config)(void);
153 
154 /*! \brief A callback function for allocating an object to hold all config objects
155  * \retval NULL error
156  * \retval non-NULL a config object container
157  */
158 typedef void *(*aco_snapshot_alloc)(void);
159 
160 /*! \brief The representation of a single configuration file to be processed */
161 struct aco_file {
162  const char *filename; /*!< The filename to be processed */
163  const char *alias; /*!< An alias filename to be tried if 'filename' cannot be found */
164  const char **preload; /*!< A null-terminated ordered array of categories to be loaded first */
165  const char *skip_category; /*!< A regular expression of categories to skip in the file. Use when a file is processed by multiple modules */
166  struct aco_type *types[]; /*!< The list of types for this config. Required. Use a sentinel! */
167 };
168 
169 struct aco_info {
170  const char *module; /*!< The name of the module whose config is being processed */
171  unsigned int hidden:1; /*!< If enabled, this config item is hidden from users */
172  aco_pre_apply_config pre_apply_config; /*!< A callback called after processing, but before changes are applied */
173  aco_post_apply_config post_apply_config;/*!< A callback called after changes are applied */
174  aco_snapshot_alloc snapshot_alloc; /*!< Allocate an object to hold all global configs and item containers */
175  struct ao2_global_obj *global_obj; /*!< The global object array that holds the user-defined config object */
176  struct aco_info_internal *internal;
177  struct aco_file *files[]; /*!< An array of aco_files to process */
178 };
179 
180 /*! \brief A helper macro to ensure that aco_info types always have a sentinel */
181 #define ACO_TYPES(...) { __VA_ARGS__, NULL, }
182 #define ACO_FILES(...) { __VA_ARGS__, NULL, }
183 
184 /*! \brief Get pending config changes
185  * \note This will most likely be called from the pre_apply_config callback function
186  * \param info An initialized aco_info
187  * \retval NULL error
188  * \retval non-NULL A pointer to the user-defined config object with un-applied changes
189  */
190 void *aco_pending_config(struct aco_info *info);
191 
192 /*! \def CONFIG_INFO_STANDARD
193  * \brief Declare an aco_info struct with default module and preload values
194  * \param name The name of the struct
195  * \param arr The global object array for holding the user-defined config object
196  * \param alloc The allocater for the user-defined config object
197  *
198  * Example:
199  * \code
200  * static AO2_GLOBAL_OBJ_STATIC(globals, 1);
201  * CONFIG_INFO_STANDARD(cfg_info, globals, skel_config_alloc,
202  * .pre_apply_config = skel_pre_apply_config,
203  * .files = { &app_skel_conf, NULL },
204  * );
205  * ...
206  * if (aco_info_init(&cfg_info)) {
207  * return AST_MODULE_LOAD_DECLINE;
208  * }
209  * ...
210  * aco_info_destroy(&cfg_info);
211  * \endcode
212  */
213 #define CONFIG_INFO_STANDARD(name, arr, alloc, ...) \
214 static struct aco_info name = { \
215  .module = AST_MODULE, \
216  .global_obj = &arr, \
217  .snapshot_alloc = alloc, \
218  __VA_ARGS__ \
219 };
220 
221 #define CONFIG_INFO_CORE(mod, name, arr, alloc, ...) \
222 static struct aco_info name = { \
223  .module = mod, \
224  .global_obj = &arr, \
225  .snapshot_alloc = alloc, \
226  __VA_ARGS__ \
227 };
228 
229 #define CONFIG_INFO_TEST(name, arr, alloc, ...) \
230 static struct aco_info name = { \
231  .module = AST_MODULE, \
232  .global_obj = &arr, \
233  .snapshot_alloc = alloc, \
234  .hidden = 1, \
235  __VA_ARGS__ \
236 };
237 
238 /*! \brief Initialize an aco_info structure
239  * \note aco_info_destroy must be called if this succeeds
240  * \param info The address of an aco_info struct to initialize
241  * \retval 0 Success
242  * \retval non-zero Failure
243  */
244 int aco_info_init(struct aco_info *info);
245 
246 /*! \brief Destroy an initialized aco_info struct
247  * \param info The address of the aco_info struct to destroy
248  */
249 void aco_info_destroy(struct aco_info *info);
250 
251 /*! \brief The option types
252  *
253  * \note aco_option_register takes an option type which is used
254  * to look up the handler for that type. Each non-custom type requires
255  * field names for specific types in the struct being configured. Each
256  * option below is commented with the field types, additional arguments
257  * and example usage with aco_option_register
258  */
260  /*! \brief Type for default option handler for ACLs
261  * \note aco_option_register flags:
262  * non-zero : "permit"
263  * 0 : "deny"
264  * aco_option_register varargs:
265  * FLDSET macro with the field of type struct ast_ha *.
266  *
267  * Example:
268  * {code}
269  * struct test_item {
270  * struct ast_ha *ha;
271  * };
272  * aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
273  * aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
274  * {code}
275  */
277 
278  /*! \brief Type for default option handler for bools (ast_true/ast_false)
279  * \note aco_option_register flags:
280  * non-zero : process via ast_true
281  * 0 : process via ast_false
282  * aco_option_register varargs:
283  * FLDSET macro with the field of type int. It is important to note that the field
284  * cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
285  *
286  * Example:
287  * {code}
288  * struct test_item {
289  * int enabled;
290  * };
291  * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
292  * {endcode}
293  */
295 
296  /*! \brief Type for default option handler for bools (ast_true/ast_false) that are stored in a flag
297  * \note aco_option_register flags:
298  * non-zero : process via ast_true
299  * 0 : process via ast_false
300  * aco_option_register varargs:
301  * FLDSET macro with the field of type of unsigned int.
302  * The flag to set
303  *
304  * Example:
305  * {code}
306  * #define MY_TYPE_ISQUIET 1 << 4
307  * struct test_item {
308  * unsigned int flags;
309  * };
310  * aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET);
311  * {endcode}
312  */
314 
315  /*! \brief Type for default option handler for character array strings
316  * \note aco_option_register flags:
317  * non-zero : String cannot be empty.
318  * 0 : String can be empty.
319  * \note aco_option_register varargs:
320  * CHARFLDSET macro with a field of type char[]
321  *
322  * Example:
323  * {code}
324  * struct test_item {
325  * char description[128];
326  * };
327  * aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description));
328  * {endcode}
329  */
331 
332  /*! \brief Type for default option handler for format capabilities
333  * \note aco_option_register flags:
334  * non-zero : This is an "allow" style option
335  * 0 : This is a "disallow" style option
336  * aco_option_register varargs:
337  * FLDSET macro with field representing a struct ast_format_cap *
338  *
339  * Example:
340  * {code}
341  * struct test_item {
342  * struct ast_format cap *cap;
343  * };
344  * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
345  * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
346  * {endcode}
347  */
349 
350  /*! \brief Type for a custom (user-defined) option handler */
352 
353  /*! \brief Type for default option handler for doubles
354  *
355  * \note aco_option_register flags:
356  * See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function
357  * aco_option_register varargs:
358  * FLDSET macro with the field of type double
359  *
360  * Example:
361  * struct test_item {
362  * double dub;
363  * };
364  * {code}
365  * aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
366  * {endcode}
367  */
369 
370  /*! \brief Type for default option handler for signed integers
371  *
372  * \note aco_option_register flags:
373  * See flags available for use with the PARSE_INT32 type for the ast_parse_arg function
374  * aco_option_register varargs:
375  * FLDSET macro with the field of type int32_t
376  * The remaining varargs for should be arguments compatible with the varargs for the
377  * ast_parse_arg function with the PARSE_INT32 type and the flags passed in the
378  * aco_option_register flags parameter.
379  *
380  * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
381  * contains an invalid value, it is better to let the config loading fail with warnings so that
382  * the problem is fixed by the administrator.
383  *
384  * Example:
385  * struct test_item {
386  * int32_t intopt;
387  * };
388  * {code}
389  * aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
390  * {endcode}
391  */
393 
394  /*! \brief Type for a default handler that should do nothing
395  *
396  * \note This might be useful for a "type" field that is valid, but doesn't
397  * actually need to do anything
398  */
400 
401  /*! \brief Type for default handler for ast_sockaddrs
402  *
403  * \note aco_option_register flags:
404  * See flags available for use with the PARSE_ADDR type for the ast_parse_arg function
405  * aco_option_register varargs:
406  * FLDSET macro with the field being of type struct ast_sockaddr.
407  *
408  * Example:
409  * {code}
410  * struct test_item {
411  * struct ast_sockaddr addr;
412  * };
413  * aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
414  * {endcode}
415  */
417 
418  /*! \brief Type for default option handler for stringfields
419  * \note aco_option_register flags:
420  * non-zero : String cannot be empty.
421  * 0 : String can be empty.
422  * aco_option_register varargs:
423  * STRFLDSET macro with the field being the field created by AST_STRING_FIELD
424  *
425  * Example:
426  * {code}
427  * struct test_item {
428  * AST_DECLARE_STRING_FIELDS(
429  * AST_STRING_FIELD(thing);
430  * );
431  * };
432  * aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing));
433  * {endcode}
434  */
436 
437  /*! \brief Type for default option handler for unsigned integers
438  *
439  * \note aco_option_register flags:
440  * See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function
441  * aco_option_register varargs:
442  * FLDSET macro with the field of type uint32_t
443  * The remaining varargs for should be arguments compatible with the varargs for the
444  * ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the
445  * aco_option_register flags parameter.
446  *
447  * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
448  * contains an invalid value, it is better to let the config loading fail with warnings so that
449  * the problem is fixed by the administrator.
450  *
451  * Example:
452  * struct test_item {
453  * int32_t intopt;
454  * };
455  * {code}
456  * aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
457  * {endcode}
458  */
460 
461  /*! \brief Type for default option handler for bools (ast_true/ast_false)
462  * \note aco_option_register flags:
463  * non-zero : process via ast_true
464  * 0 : process via ast_false
465  * aco_option_register varargs:
466  * FLDSET macro with the field of type int. It is important to note that the field
467  * cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
468  *
469  * This is exactly the same as OPT_BOOL_T. The only difference is that when
470  * translated to a string, OPT_BOOL_T becomes "true" or "false"; OPT_YESNO_T becomes
471  * "yes" or "no".
472  *
473  * Example:
474  * {code}
475  * struct test_item {
476  * int enabled;
477  * };
478  * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled));
479  * {endcode}
480  */
482 
483  /*! \brief Type for default option handler for time length signed integers
484  *
485  * \note aco_option_register flags:
486  * See flags available for use with the PARSE_TIMELEN type for the ast_parse_arg function
487  * aco_option_register varargs:
488  * FLDSET macro with the field of type int
489  * The remaining varargs for should be arguments compatible with the varargs for the
490  * ast_parse_arg function with the PARSE_TIMELEN type and the flags passed in the
491  * aco_option_register flags parameter.
492  *
493  * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
494  * contains an invalid value, it is better to let the config loading fail with warnings so that
495  * the problem is fixed by the administrator.
496  *
497  * Example:
498  * struct test_item {
499  * int timelen;
500  * };
501  * {code}
502  * aco_option_register(&cfg_info, "timelen", ACO_EXACT, my_types, "3", OPT_TIMELEN_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), TIMELEN_MILLISECONDS, -10, 10);
503  * {endcode}
504  */
506 
507 };
508 
509 /*! \brief A callback function for handling a particular option
510  * \param opt The option being configured
511  * \param var The config variable to use to configure \a obj
512  * \param obj The object to be configured
513  *
514  * \retval 0 Parsing and recording the config value succeeded
515  * \retval non-zero Failure. Parsing should stop and no reload applied
516  */
517 typedef int (*aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj);
518 
519 /*! \brief Allocate a container to hold config options */
521 
522 /*! \brief Return values for the aco_process functions
523  */
525  ACO_PROCESS_OK, /*!< \brief The config was processed and applied */
526  ACO_PROCESS_UNCHANGED, /*!< \brief The config had not been edited and no changes applied */
527  ACO_PROCESS_ERROR, /*!< \brief Their was an error and no changes were applied */
528 };
529 
530 /*! \brief Process a config info via the options registered with an aco_info
531  *
532  * \param info The config_options_info to be used for handling the config
533  * \param reload Non-zero if this is for a reload.
534  *
535  * \retval ACO_PROCESS_OK Success
536  * \retval ACO_PROCESS_ERROR Failure
537  * \retval ACO_PROCESS_UNCHANGED No change due to unedited config file
538  */
540 
541 /*! \brief Process config info from an ast_config via options registered with an aco_info
542  *
543  * \param info The aco_info to be used for handling the config
544  * \param file The file attached to aco_info that the config represents
545  * \param cfg A pointer to a loaded ast_config to parse
546  *
547  * \retval ACO_PROCESS_OK Success
548  * \retval ACO_PROCESS_ERROR Failure
549  */
551 
552 /*! \brief Parse a single ast_variable and apply it to an object
553  * \note This function can be used to build up an object by repeatedly passing in
554  * the config variable name and values that would be found in a config file. This can
555  * be useful if the object is to be populated by a dialplan function, for example.
556  *
557  * \param type The aco_type associated with the object
558  * \param cat The category to use
559  * \param var A variable to apply to the object
560  * \param obj A pointer to the object to be configured
561  *
562  * \retval 0 Success
563  * \retval -1 Failure
564  */
565 int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable *var, void *obj);
566 
567 /*! \brief Parse each option defined in a config category
568  * \param type The aco_type with the options for parsing
569  * \param cfg The ast_config being parsed
570  * \param cat The config category being parsed
571  * \param obj The user-defined config object that will store the parsed config items
572  *
573  * \retval 0 Success
574  * \retval -1 Failure
575  */
576 int aco_process_category_options(struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj);
577 
578 /*! \brief Set all default options of \a obj
579  * \param type The aco_type with the options
580  * \param category The configuration category from which \a obj is being configured
581  * \param obj The object being configured
582  *
583  * \retval 0 Success
584  * \retval -1 Failure
585  */
586 int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
587 
588 /*! \brief register a config option
589  *
590  * \note this should probably only be called by one of the aco_option_register* macros
591  *
592  * \param info The aco_info holding this module's config information
593  * \param name The name of the option
594  * \param match_type
595  * \param types An array of valid option types for matching categories to the correct struct type
596  * \param default_val The default value of the option in the same format as defined in a config file
597  * \param type The option type (only for default handlers)
598  * \param handler The handler function for the option (only for non-default types)
599  * \param flags a type specific flags, stored in the option and available to the handler
600  * \param no_doc if non-zero, this option should not have documentation
601  * \param argc The number for variadic arguments
602  * \param ... field offsets to store for default handlers
603  *
604  * \retval 0 success
605  * \retval -1 failure
606  */
607 int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types,
608  const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc, ...);
609 
610 /*! \brief Register a config option
611  * \param info A pointer to the aco_info struct
612  * \param name The name of the option
613  * \param matchtype
614  * \param types An array of valid option types for matching categories to the correct struct type
615  * \param default_val The default value of the option in the same format as defined in a config file
616  * \param opt_type The option type for default option type handling
617  * \param flags a type specific flags, stored in the option and available to the handler
618  * \param ...
619  *
620  * \retval 0 Success
621  * \retval -1 Failure
622  */
623 #define aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...) \
624  __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
625 
626 /*! \brief Register a config option
627  * \param info A pointer to the aco_info struct
628  * \param name The name of the option
629  * \param matchtype
630  * \param types An array of valid option types for matching categories to the correct struct type
631  * \param default_val The default value of the option in the same format as defined in a config file
632  * \param handler The handler callback for the option
633  * \param flags \a type specific flags, stored in the option and available to the handler
634  *
635  * \retval 0 Success
636  * \retval -1 Failure
637  */
638 #define aco_option_register_custom(info, name, matchtype, types, default_val, handler, flags) \
639  __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
640 
641 /*! \brief Register a config option with no expected documentation
642  * \param info A pointer to the aco_info struct
643  * \param name The name of the option
644  * \param matchtype
645  * \param types An array of valid option types for matching categories to the correct struct type
646  * \param default_val The default value of the option in the same format as defined in a config file
647  * \param handler The handler callback for the option
648  * \param flags \a type specific flags, stored in the option and available to the handler
649  *
650  * \note This is used primarily with custom options that only have internal purposes
651  * and that should be ignored by the user.
652  *
653  * \retval 0 Success
654  * \retval -1 Failure
655  */
656 #define aco_option_register_custom_nodoc(info, name, matchtype, types, default_val, handler, flags) \
657  __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);
658 
659 /*! \brief Register a deprecated (and aliased) config option
660  * \param info A pointer to the aco_info struct
661  * \param name The name of the deprecated option
662  * \param types An array of valid option types for matching categories to the correct struct type
663  * \param aliased_to The name of the option that this deprecated option matches to
664  *
665  * \retval 0 Success
666  * \retval -1 Failure
667  */
668 int aco_option_register_deprecated(struct aco_info *info, const char *name, struct aco_type **types, const char *aliased_to);
669 
670 /*!
671  * \brief Read the flags of a config option - useful when using a custom callback for a config option
672  * \since 12
673  *
674  * \param option Pointer to the aco_option struct
675  *
676  * \retval value of the flags on the config option
677  */
678 unsigned int aco_option_get_flags(const struct aco_option *option);
679 
680 /*!
681  * \brief Get the offset position for an argument within a config option
682  *
683  * \param option Pointer to the aco_option struct
684  * \param arg Argument number
685  *
686  * \retval position of the argument
687  */
688 intptr_t aco_option_get_argument(const struct aco_option *option, unsigned int position);
689 
690 /*! \note Everything below this point is to handle converting varargs
691  * containing field names, to varargs containing a count of args, followed
692  * by the offset of each of the field names in the struct type that is
693  * passed in. It is currently limited to 8 arguments, but 8 variadic
694  * arguments, like 640K, should be good enough for anyone. If not, it is
695  * easy to add more.
696  *
697  */
698 
699 /*!
700  * \brief Map \a func(\a func_arg, field) across all fields including \a x
701  * \param func The function (almost certainly offsetof) to map across the fields
702  * \param func_arg The first argument (almost certainly a type (e.g. "struct mystruct")
703  * \param x The first field
704  * \param ... varargs The rest of the fields
705  *
706  * Example usage:
707  * \code
708  * struct foo {
709  * int a;
710  * char *b;
711  * foo *c;
712  * };
713  * ARGMAP(offsetof, struct foo, a, c)
714  * \endcode
715  *
716  * produces the string:
717  *
718  * \code
719  * 2, offsetof(struct foo, a), offsetof(struct foo, b)
720  * \endcode
721  * which can be passed as the varargs to some other function
722  *
723  * The macro isn't limited to offsetof, but that is the only purpose for
724  * which it has been tested.
725  *
726  * As an example of how the processing works:
727  * \verbatim
728  * ARGMAP(offsetof, struct foo, a, b, c) ->
729  * ARGMAP_(3, offsetof, struct foo, a, b, c) ->
730  * ARGMAP_3(offsetof, struct foo, 3, a, b, c) ->
731  * ARGMAP_2(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a)), b, c) ->
732  * ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) ->
733  * ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) ->
734  * 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)
735  * \endverbatim
736  *
737  */
738 #define ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
739 
740 /*! \note This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so
741  * that the accumulation both works properly for the first argument (since "in" can't be empty) and
742  * we get the number of arguments in our varargs as a bonus
743  */
744 #define ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)
745 
746 /*! \def PASTE(arg1, arg2)
747  * \brief Paste two arguments together, even if they are macros themselves
748  * \note Uses two levels to handle the case where arg1 and arg2 are macros themselves
749  */
750 #define PASTE(arg1, arg2) PASTE1(arg1, arg2)
751 #define PASTE1(arg1, arg2) arg1##arg2
752 
753 /*! \brief Take a comma-separated list and allow it to be passed as a single argument to another macro */
754 #define ARGIFY(...) __VA_ARGS__
755 
756 /*! \brief The individual field handlers for ARGMAP
757  * \param func The function (most likely offsetof)
758  * \param func_arg The first argument to func (most likely a type e.g. "struct my_struct")
759  * \param in The accumulated function-mapped field names so far
760  * \param x The next field name
761  * \param ... varargs The rest of the field names
762  */
763 #define ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x))
764 #define ARGMAP_2(func, func_arg, in, x, ...)\
765  ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
766 #define ARGMAP_3(func, func_arg, in, x, ...)\
767  ARGMAP_2(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
768 #define ARGMAP_4(func, func_arg, in, x, ...)\
769  ARGMAP_3(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
770 #define ARGMAP_5(func, func_arg, in, x, ...)\
771  ARGMAP_4(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
772 #define ARGMAP_6(func, func_arg, in, x, ...)\
773  ARGMAP_5(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
774 #define ARGMAP_7(func, func_arg, in, x, ...)\
775  ARGMAP_6(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
776 #define ARGMAP_8(func, func_arg, in, x, ...)\
777  ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
778 
779 /*! \def VA_NARGS(...)
780  * \brief Results in the number of arguments passed to it
781  * \note Currently only up to 8, but expanding is easy. This macro basically counts
782  * commas + 1. To visualize:
783  * \verbatim
784  * VA_NARGS(one, two, three) -> v
785  * VA_NARGS1(one, two, three, 8, 7, 6, 5, 4, 3, 2, 1, 0) ->
786  * VA_NARGS1( _1, _2, _3, _4, _5, _6, _7, _8, N, ... ) N -> 3
787  *
788  * Note that VA_NARGS *does not* work when there are no arguments passed. Pasting an empty
789  * __VA_ARGS__ with a comma like ", ##__VA_ARGS__" will delete the leading comma, but it
790  * does not work when __VA_ARGS__ is the first argument. Instead, 1 is returned instead of 0:
791  *
792  * VA_NARGS() -> v
793  * VA_NARGS1( , 8, 7, 6, 5, 4, 3, 2, 1, 0) ->
794  * VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N) -> 1
795  * \endverbatim
796  */
797 #define VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
798 #define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N
799 
800 /*! \def FLDSET(type, ...)
801  * \brief Convert a struct and list of fields to an argument list of field offsets
802  * \param type The type with the fields (e.g. "struct my_struct")
803  * \param ... varags The fields in the struct whose offsets are needed as arguments
804  *
805  * For example:
806  * \code
807  * struct foo {int a, char b[128], char *c};
808  * FLDSET(struct foo, a, c)
809  * \endcode
810  *
811  * produces
812  * \code
813  * offsetof(struct foo, a), offsetof(struct foo, c)
814  * \endcode
815  */
816 #define FLDSET(type, ...) FLDSET1(type, ##__VA_ARGS__)
817 #define FLDSET1(type, ...) POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))
818 
819 /*! \def STRFLDSET(type, ...)
820  * \brief Convert a struct and a list of stringfield fields to an argument list of field offsets
821  * \note Stringfields require the passing of the field manager pool, and field manager to the
822  * default stringfield option handler, so registering options that point to stringfields requires
823  * this macro to be called instead of the FLDSET macro.
824  * \param type The type with the fields (e.g. "struct my_struct")
825  * \param ... varargs The fields in the struct whose offsets are needed as arguments
826  */
827 #define STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
828 
829 /*! \def CHARFLDSET(type, field)
830  * \brief A helper macro to pass the appropriate arguments to aco_option_register for OPT_CHAR_ARRAY_T
831  * \note This will pass the offset of the field and its length as arguments
832  * \param type The type with the char array field (e.g. "struct my_struct")
833  * \param field The name of char array field
834  */
835 #define CHARFLDSET(type, field) ARGIFY(offsetof(type, field), sizeof(((type *)0)->field))
836 
837 /*! \def POPPED(...)
838  * \brief A list of arguments without the first argument
839  * \note Used internally to remove the leading "number of arguments" argument from ARGMAP for
840  * FLDSET. This is because a call to FLDSET may be followed by additional arguments in
841  * aco_register_option, so the true number of arguments will possibly be different than what
842  * ARGMAP returns.
843  * \param ... varags A list of arguments
844  * \verbatim
845  * POPPED(a, b, c) -> b, c
846  * \endverbatim
847  */
848 #define POPPED(...) POPPED1(__VA_ARGS__)
849 #define POPPED1(x, ...) __VA_ARGS__
850 
851 #if defined(__cplusplus) || defined(c_plusplus)
852 }
853 #endif
854 
855 #endif /* _ASTERISK_CONFIG_OPTIONS_H */
aco_type_item_pre_process item_pre_process
Type for default handler for ast_sockaddrs.
Type for default option handler for format capabilities.
int(* aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj)
A callback function for handling a particular option.
const char * matchfield
aco_pre_apply_config pre_apply_config
aco_type_item_find item_find
struct ao2_global_obj * global_obj
void(* aco_post_apply_config)(void)
A callback function called only if config changes have been applied.
int(* aco_pre_apply_config)(void)
A callback function to run just prior to applying config changes.
unsigned int aco_option_get_flags(const struct aco_option *option)
Read the flags of a config option - useful when using a custom callback for a config option...
void *(* aco_snapshot_alloc)(void)
A callback function for allocating an object to hold all config objects.
static int reload(void)
struct ao2_container * aco_option_container_alloc(void)
Allocate a container to hold config options.
Structure for variables, used for configurations and for channel variables.
#define var
Definition: ast_expr2f.c:614
aco_type_prelink item_prelink
Type for a default handler that should do nothing.
enum aco_process_status aco_process_config(struct aco_info *info, int reload)
Process a config info via the options registered with an aco_info.
Type for default option handler for bools (ast_true/ast_false) that are stored in a flag...
char * text
Definition: app_queue.c:1514
The representation of a single configuration file to be processed.
Bits of aco_info that shouldn&#39;t be assigned outside this file.
enum aco_type_t type
aco_matchtype
What kind of matching should be done on an option name.
aco_type_t
Type for a custom (user-defined) option handler.
const char * alias
Type for default option handler for character array strings.
Type for default option handler for bools (ast_true/ast_false)
Configuration File Parser.
const char * matchvalue
int aco_info_init(struct aco_info *info)
Initialize an aco_info structure.
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
void * aco_pending_config(struct aco_info *info)
Get pending config changes.
Type for default option handler for unsigned integers.
unsigned int hidden
const char * category
int(* aco_matchvalue_func)(const char *text)
A function for determining whether the value for the matchfield in an aco_type is sufficient for a ma...
aco_process_status
Return values for the aco_process functions.
int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types, const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc,...)
register a config option
aco_type_item_alloc item_alloc
int aco_option_register_deprecated(struct aco_info *info, const char *name, struct aco_type **types, const char *aliased_to)
Register a deprecated (and aliased) config option.
enum aco_category_op category_match
aco_option_type
The option types.
The config had not been edited and no changes applied.
Their was an error and no changes were applied.
aco_post_apply_config post_apply_config
void aco_info_destroy(struct aco_info *info)
Destroy an initialized aco_info struct.
Type for default option handler for bools (ast_true/ast_false)
def info(msg)
int aco_process_category_options(struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj)
Parse each option defined in a config category.
Type for default option handler for ACLs.
enum aco_process_status aco_process_ast_config(struct aco_info *info, struct aco_file *file, struct ast_config *cfg)
Process config info from an ast_config via options registered with an aco_info.
Type for default option handler for doubles.
int aco_set_defaults(struct aco_type *type, const char *category, void *obj)
Set all default options of obj.
const char ** preload
The config was processed and applied.
const char * skip_category
int(* aco_type_item_pre_process)(void *newitem)
Callback function that is called after a config object is initialized with defaults.
const char * name
Type for default option handler for time length signed integers.
Type information about a category-level configurable object.
aco_snapshot_alloc snapshot_alloc
size_t item_offset
const char * filename
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59
intptr_t aco_option_get_argument(const struct aco_option *option, unsigned int position)
Get the offset position for an argument within a config option.
Type for default option handler for stringfields.
Generic container type.
const char * module
Type for default option handler for signed integers.
int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable *var, void *obj)
Parse a single ast_variable and apply it to an object.
aco_category_op
aco_matchvalue_func matchfunc
void *(* aco_type_item_find)(struct ao2_container *newcontainer, const char *category)
Find a item given a category and container of items.
int(* aco_type_prelink)(void *newitem)
Callback function that is called after config processing, but before linking.
unsigned int hidden