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