Asterisk - The Open Source Telephony Project GIT-master-67613d1
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)
28extern "C" {
29#endif
30
31#include <regex.h>
32
33#include "asterisk/config.h"
34#include "asterisk/astobj2.h"
35
36struct aco_option;
39
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 */
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 */
76typedef void *(*aco_type_item_alloc)(const char *category);
77
78/*! \brief Find a item given a category and container of items
79 * \param newcontainer 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 */
84typedef 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 */
97typedef 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 */
109typedef 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 */
116typedef int (*aco_matchvalue_func)(const char *text);
117
118/*! \struct aco_type
119 * \brief Type information about a category-level configurable object
120 */
121struct 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') */
128 aco_matchvalue_func matchfunc; /*!< A function for determining whether the option value matches */
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 */
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 */
145typedef 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 */
152typedef 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 */
158typedef void *(*aco_snapshot_alloc)(void);
159
160/*! \brief The representation of a single configuration file to be processed */
161struct 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
169struct 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 */
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 */
190void *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, ...) \
214static 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, ...) \
222static 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, ...) \
230static 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 */
244int 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 */
249void 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 * \endcode
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 */
517typedef 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 */
565int 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 */
576int 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 */
586int 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 */
607int __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 */
668int 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 */
678unsigned 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 position Argument number
685 *
686 * \retval position of the argument
687 */
688intptr_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 */
char * text
Definition: app_queue.c:1639
#define var
Definition: ast_expr2f.c:605
static const char type[]
Definition: chan_ooh323.c:109
struct ao2_container * aco_option_container_alloc(void)
Allocate a container to hold config options.
int(* aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj)
A callback function for handling a particular option.
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.
aco_matchtype
What kind of matching should be done on an option name.
@ ACO_PREFIX
@ ACO_EXACT
@ ACO_REGEX
int aco_set_defaults(struct aco_type *type, const char *category, void *obj)
Set all default options of obj.
void aco_info_destroy(struct aco_info *info)
Destroy an initialized aco_info struct.
aco_process_status
Return values for the aco_process functions.
@ ACO_PROCESS_UNCHANGED
The config had not been edited and no changes applied.
@ ACO_PROCESS_ERROR
Their was an error and no changes were applied.
@ ACO_PROCESS_OK
The config was processed and applied.
int aco_info_init(struct aco_info *info)
Initialize an aco_info structure.
void *(* aco_snapshot_alloc)(void)
A callback function for allocating an object to hold all config objects.
aco_option_type
The option types.
@ OPT_UINT_T
Type for default option handler for unsigned integers.
@ OPT_NOOP_T
Type for a default handler that should do nothing.
@ OPT_CODEC_T
Type for default option handler for format capabilities.
@ OPT_BOOL_T
Type for default option handler for bools (ast_true/ast_false)
@ OPT_BOOLFLAG_T
Type for default option handler for bools (ast_true/ast_false) that are stored in a flag.
@ OPT_CUSTOM_T
Type for a custom (user-defined) option handler.
@ OPT_CHAR_ARRAY_T
Type for default option handler for character array strings.
@ OPT_ACL_T
Type for default option handler for ACLs.
@ OPT_SOCKADDR_T
Type for default handler for ast_sockaddrs.
@ OPT_YESNO_T
Type for default option handler for bools (ast_true/ast_false)
@ OPT_INT_T
Type for default option handler for signed integers.
@ OPT_TIMELEN_T
Type for default option handler for time length signed integers.
@ OPT_DOUBLE_T
Type for default option handler for doubles.
@ OPT_STRINGFIELD_T
Type for default option handler for stringfields.
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_post_apply_config)(void)
A callback function called only if config changes have been applied.
void *(* aco_type_item_alloc)(const char *category)
Allocate a configurable ao2 object.
aco_type_t
@ ACO_ITEM
@ ACO_GLOBAL
@ ACO_IGNORE
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.
int(* aco_type_item_pre_process)(void *newitem)
Callback function that is called after a config object is initialized with defaults.
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.
aco_category_op
@ ACO_WHITELIST_ARRAY
@ ACO_BLACKLIST
@ ACO_WHITELIST_EXACT
@ ACO_WHITELIST
@ ACO_BLACKLIST_ARRAY
@ ACO_BLACKLIST_EXACT
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.
int(* aco_pre_apply_config)(void)
A callback function to run just prior to applying config changes.
int(* aco_type_prelink)(void *newitem)
Callback function that is called after config processing, but before linking.
void *(* aco_type_item_find)(struct ao2_container *newcontainer, const char *category)
Find a item given a category and container of items.
void * aco_pending_config(struct aco_info *info)
Get pending config changes.
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
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...
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.
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.
static const char name[]
Definition: format_mp3.c:68
Configuration File Parser.
def info(msg)
static int reload(void)
The representation of a single configuration file to be processed.
const char ** preload
struct aco_type * types[]
const char * filename
const char * skip_category
const char * alias
Bits of aco_info that shouldn't be assigned outside this file.
struct aco_file * files[]
unsigned int hidden
struct ao2_global_obj * global_obj
aco_snapshot_alloc snapshot_alloc
struct aco_info_internal * internal
aco_post_apply_config post_apply_config
const char * module
aco_pre_apply_config pre_apply_config
Type information about a category-level configurable object.
const char * category
aco_type_prelink item_prelink
aco_type_item_pre_process item_pre_process
unsigned int hidden
aco_type_item_find item_find
enum aco_type_t type
aco_matchvalue_func matchfunc
const char * matchfield
aco_type_item_alloc item_alloc
const char * name
struct aco_type_internal * internal
const char * matchvalue
size_t item_offset
enum aco_category_op category_match
Generic container type.
Structure for variables, used for configurations and for channel variables.
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