Configuration option-handling. More...

#include <regex.h>
#include "asterisk/config.h"
#include "asterisk/astobj2.h"

Include dependency graph for config_options.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	aco_file
	The representation of a single configuration file to be processed. More...

struct	aco_info

struct	aco_type
	Type information about a category-level configurable object. More...

Macros
#define	ACO_FILES(...) { __VA_ARGS__, NULL, }

#define	aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...) __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
	Register a config option. More...

#define	aco_option_register_custom(info, name, matchtype, types, default_val, handler, flags) __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
	Register a config option. More...

#define	aco_option_register_custom_nodoc(info, name, matchtype, types, default_val, handler, flags) __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);
	Register a config option with no expected documentation. More...

#define	ACO_TYPES(...) { __VA_ARGS__, NULL, }
	A helper macro to ensure that aco_info types always have a sentinel. More...

#define	ARGIFY(...) __VA_ARGS__
	Take a comma-separated list and allow it to be passed as a single argument to another macro. More...

#define	ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
	Map func(func_arg, field) across all fields including x. More...

#define	ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)

#define	ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x))
	The individual field handlers for ARGMAP. More...

#define	ARGMAP_2(func, func_arg, in, x, ...) ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_3(func, func_arg, in, x, ...) ARGMAP_2(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_4(func, func_arg, in, x, ...) ARGMAP_3(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_5(func, func_arg, in, x, ...) ARGMAP_4(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_6(func, func_arg, in, x, ...) ARGMAP_5(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_7(func, func_arg, in, x, ...) ARGMAP_6(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	ARGMAP_8(func, func_arg, in, x, ...) ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

#define	CHARFLDSET(type, field) ARGIFY(offsetof(type, field), sizeof(((type *)0)->field))
	A helper macro to pass the appropriate arguments to aco_option_register for OPT_CHAR_ARRAY_T. More...

#define	CONFIG_INFO_CORE(mod, name, arr, alloc, ...)

#define	CONFIG_INFO_STANDARD(name, arr, alloc, ...)
	Declare an aco_info struct with default module and preload values. More...

#define	CONFIG_INFO_TEST(name, arr, alloc, ...)

#define	FLDSET(type, ...) FLDSET1(type, ##__VA_ARGS__)
	Convert a struct and list of fields to an argument list of field offsets. More...

#define	FLDSET1(type, ...) POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))

#define	PASTE(arg1, arg2) PASTE1(arg1, arg2)
	Paste two arguments together, even if they are macros themselves. More...

#define	PASTE1(arg1, arg2) arg1##arg2

#define	POPPED(...) POPPED1(__VA_ARGS__)
	A list of arguments without the first argument. More...

#define	POPPED1(x, ...) __VA_ARGS__

#define	STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
	Convert a struct and a list of stringfield fields to an argument list of field offsets. More...

#define	VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
	Results in the number of arguments passed to it. More...

#define	VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N

Typedefs
typedef 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 match. More...

typedef int(*	aco_option_handler) (const struct aco_option opt, struct ast_variable var, void *obj)
	A callback function for handling a particular option. More...

typedef void(*	aco_post_apply_config) (void)
	A callback function called only if config changes have been applied. More...

typedef int(*	aco_pre_apply_config) (void)
	A callback function to run just prior to applying config changes. More...

typedef void (	aco_snapshot_alloc) (void)
	A callback function for allocating an object to hold all config objects. More...

typedef void (	aco_type_item_alloc) (const char *category)
	Allocate a configurable ao2 object. More...

typedef void (	aco_type_item_find) (struct ao2_container newcontainer, const char category)
	Find a item given a category and container of items. More...

typedef int(*	aco_type_item_pre_process) (void *newitem)
	Callback function that is called after a config object is initialized with defaults. More...

typedef int(*	aco_type_prelink) (void *newitem)
	Callback function that is called after config processing, but before linking. More...

Enumerations
enum	aco_category_op { ACO_BLACKLIST = 0, ACO_WHITELIST, ACO_BLACKLIST_EXACT, ACO_WHITELIST_EXACT, ACO_BLACKLIST_ARRAY, ACO_WHITELIST_ARRAY }

enum	aco_matchtype { ACO_EXACT = 1, ACO_REGEX, ACO_PREFIX }
	What kind of matching should be done on an option name. More...

enum	aco_option_type { OPT_ACL_T, OPT_BOOL_T, OPT_BOOLFLAG_T, OPT_CHAR_ARRAY_T, OPT_CODEC_T, OPT_CUSTOM_T, OPT_DOUBLE_T, OPT_INT_T, OPT_NOOP_T, OPT_SOCKADDR_T, OPT_STRINGFIELD_T, OPT_UINT_T, OPT_YESNO_T, OPT_TIMELEN_T }
	The option types. More...

enum	aco_process_status { ACO_PROCESS_OK, ACO_PROCESS_UNCHANGED, ACO_PROCESS_ERROR }
	Return values for the aco_process functions. More...

enum	aco_type_t { ACO_GLOBAL, ACO_ITEM, ACO_IGNORE }

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 More...

void	aco_info_destroy (struct aco_info *info)
	Destroy an initialized aco_info struct. More...

int	aco_info_init (struct aco_info *info)
	Initialize an aco_info structure. More...

struct ao2_container *	aco_option_container_alloc (void)
	Allocate a container to hold config options. More...

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. More...

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. More...

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. More...

void *	aco_pending_config (struct aco_info *info)
	Get pending config changes. More...

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. More...

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. More...

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. More...

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. More...

int	aco_set_defaults (struct aco_type type, const char category, void *obj)
	Set all default options of obj. More...

Detailed Description

Configuration option-handling.

Author: Terry Wilson twils.nosp@m.on@d.nosp@m.igium.nosp@m..com

Definition in file config_options.h.

Macro Definition Documentation

◆ ACO_FILES

#define ACO_FILES ( ... ) { __VA_ARGS__, NULL, }

Definition at line 182 of file config_options.h.

Referenced by agents_cfg_alloc(), check_featuregroup(), and jingle_config_alloc().

◆ aco_option_register

#define aco_option_register	(	info,
		name,
		matchtype,
		types,
		default_val,
		opt_type,
		flags,
		...
	)	__aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);

Register a config option.

Parameters

info	A pointer to the aco_info struct
name	The name of the option
matchtype
types	An array of valid option types for matching categories to the correct struct type
default_val	The default value of the option in the same format as defined in a config file
opt_type	The option type for default option type handling
flags	a type specific flags, stored in the option and available to the handler
...

Return values

0	Success
-1	Failure

Definition at line 623 of file config_options.h.

Referenced by ast_ari_config_init(), AST_TEST_DEFINE(), conf_load_config(), load_config(), load_module(), process_config(), and stasis_init().

◆ aco_option_register_custom

#define aco_option_register_custom	(	info,
		name,
		matchtype,
		types,
		default_val,
		handler,
		flags
	)	__aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);

Register a config option.

Parameters

info	A pointer to the aco_info struct
name	The name of the option
matchtype
types	An array of valid option types for matching categories to the correct struct type
default_val	The default value of the option in the same format as defined in a config file
handler	The handler callback for the option
flags	type specific flags, stored in the option and available to the handler

Return values

0	Success
-1	Failure

Definition at line 638 of file config_options.h.

Referenced by ast_ari_config_init(), AST_TEST_DEFINE(), conf_load_config(), load_config(), load_module(), and stasis_init().

◆ aco_option_register_custom_nodoc

#define aco_option_register_custom_nodoc	(	info,
		name,
		matchtype,
		types,
		default_val,
		handler,
		flags
	)	__aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);

Register a config option with no expected documentation.

Parameters

info	A pointer to the aco_info struct
name	The name of the option
matchtype
types	An array of valid option types for matching categories to the correct struct type
default_val	The default value of the option in the same format as defined in a config file
handler	The handler callback for the option
flags	type specific flags, stored in the option and available to the handler

Note: This is used primarily with custom options that only have internal purposes and that should be ignored by the user.

Return values

0	Success
-1	Failure

Definition at line 656 of file config_options.h.

Referenced by load_config().

◆ ACO_TYPES

#define ACO_TYPES ( ... ) { __VA_ARGS__, NULL, }

A helper macro to ensure that aco_info types always have a sentinel.

Definition at line 181 of file config_options.h.

◆ ARGIFY

#define ARGIFY ( ... ) __VA_ARGS__

Take a comma-separated list and allow it to be passed as a single argument to another macro.

Definition at line 754 of file config_options.h.

◆ ARGMAP

#define ARGMAP	(	func,
		func_arg,
		x,
		...
	)	ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)

Map func(func_arg, field) across all fields including x.

Note: Everything below this point is to handle converting varargs containing field names, to varargs containing a count of args, followed by the offset of each of the field names in the struct type that is passed in. It is currently limited to 8 arguments, but 8 variadic arguments, like 640K, should be good enough for anyone. If not, it is easy to add more.

Parameters

func	The function (almost certainly offsetof) to map across the fields
func_arg	The first argument (almost certainly a type (e.g. "struct mystruct")
x	The first field
...	varargs The rest of the fields

Example usage:

struct foo {
    int a;
    char *b;
    foo *c;
};
ARGMAP(offsetof, struct foo, a, c)

produces the string:

2, offsetof(struct foo, a), offsetof(struct foo, b)

which can be passed as the varargs to some other function

The macro isn't limited to offsetof, but that is the only purpose for which it has been tested.

As an example of how the processing works:

* ARGMAP(offsetof, struct foo, a, b, c) ->
* ARGMAP_(3, offsetof, struct foo, a, b, c) ->
* ARGMAP_3(offsetof, struct foo, 3, a, b, c) ->
* ARGMAP_2(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a)), b, c) ->
* ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) ->
* ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) ->
* 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)
*

Definition at line 738 of file config_options.h.

◆ ARGMAP_

#define ARGMAP_	(	N,
		func,
		func_arg,
		x,
		...
	)	PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)

Note: This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so that the accumulation both works properly for the first argument (since "in" can't be empty) and we get the number of arguments in our varargs as a bonus

Definition at line 744 of file config_options.h.

◆ ARGMAP_1

#define ARGMAP_1	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGIFY(in, func(func_arg, x))

The individual field handlers for ARGMAP.

Parameters

func	The function (most likely offsetof)
func_arg	The first argument to func (most likely a type e.g. "struct my_struct")
in	The accumulated function-mapped field names so far
x	The next field name
...	varargs The rest of the field names

Definition at line 763 of file config_options.h.

◆ ARGMAP_2

#define ARGMAP_2	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 764 of file config_options.h.

◆ ARGMAP_3

#define ARGMAP_3	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_2(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 766 of file config_options.h.

◆ ARGMAP_4

#define ARGMAP_4	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_3(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 768 of file config_options.h.

◆ ARGMAP_5

#define ARGMAP_5	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_4(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 770 of file config_options.h.

◆ ARGMAP_6

#define ARGMAP_6	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_5(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 772 of file config_options.h.

◆ ARGMAP_7

#define ARGMAP_7	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_6(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 774 of file config_options.h.

◆ ARGMAP_8

#define ARGMAP_8	(	func,
		func_arg,
		in,
		x,
		...
	)	ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)

Definition at line 776 of file config_options.h.

◆ CHARFLDSET

#define CHARFLDSET	(	type,
		field
	)	ARGIFY(offsetof(type, field), sizeof(((type *)0)->field))

A helper macro to pass the appropriate arguments to aco_option_register for OPT_CHAR_ARRAY_T.

Note: This will pass the offset of the field and its length as arguments

Parameters

type	The type with the char array field (e.g. "struct my_struct")
field	The name of char array field

Definition at line 835 of file config_options.h.

Referenced by apply_list_configuration(), ast_res_pjsip_initialize_configuration(), conf_load_config(), and load_module().

◆ CONFIG_INFO_CORE

#define CONFIG_INFO_CORE	(	mod,
		name,
		arr,
		alloc,
		...
	)

Definition at line 221 of file config_options.h.

◆ CONFIG_INFO_STANDARD

#define CONFIG_INFO_STANDARD	(	name,
		arr,
		alloc,
		...
	)

Declare an aco_info struct with default module and preload values.

Parameters

name	The name of the struct
arr	The global object array for holding the user-defined config object
alloc	The allocater for the user-defined config object

Example:

static AO2_GLOBAL_OBJ_STATIC(globals, 1);
CONFIG_INFO_STANDARD(cfg_info, globals, skel_config_alloc,
    .pre_apply_config = skel_pre_apply_config,
    .files = { &app_skel_conf, NULL },
);
...
if (aco_info_init(&cfg_info)) {
    return AST_MODULE_LOAD_DECLINE;
}
...
aco_info_destroy(&cfg_info);

Definition at line 213 of file config_options.h.

◆ CONFIG_INFO_TEST

#define CONFIG_INFO_TEST	(	name,
		arr,
		alloc,
		...
	)

Definition at line 229 of file config_options.h.

◆ FLDSET

#define FLDSET	(	type,
		...
	)	FLDSET1(type, ##__VA_ARGS__)

Convert a struct and list of fields to an argument list of field offsets.

Parameters

type	The type with the fields (e.g. "struct my_struct")
...	varags The fields in the struct whose offsets are needed as arguments

For example:

struct foo {int a, char b[128], char *c};

FLDSET(struct foo, a, c)

produces

offsetof(struct foo, a), offsetof(struct foo, c)

Definition at line 816 of file config_options.h.

Referenced by alloc_and_initialize_sorcery(), apply_list_configuration(), ast_ari_config_init(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), ast_sip_initialize_system(), AST_TEST_DEFINE(), conf_load_config(), load_config(), load_module(), mwi_sorcery_init(), process_config(), stasis_init(), and stir_shaken_general_load().

◆ FLDSET1

#define FLDSET1	(	type,
		...
	)	POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))

Definition at line 817 of file config_options.h.

◆ PASTE

#define PASTE	(	arg1,
		arg2
	)	PASTE1(arg1, arg2)

Paste two arguments together, even if they are macros themselves.

Note: Uses two levels to handle the case where arg1 and arg2 are macros themselves

Definition at line 750 of file config_options.h.

◆ PASTE1

#define PASTE1	(	arg1,
		arg2
	)	arg1##arg2

Definition at line 751 of file config_options.h.

◆ POPPED

#define POPPED ( ... ) POPPED1(__VA_ARGS__)

A list of arguments without the first argument.

Note: Used internally to remove the leading "number of arguments" argument from ARGMAP for FLDSET. This is because a call to FLDSET may be followed by additional arguments in aco_register_option, so the true number of arguments will possibly be different than what ARGMAP returns.

Parameters

...	varags A list of arguments * POPPED(a, b, c) -> b, c *

Definition at line 848 of file config_options.h.

◆ POPPED1

#define POPPED1	(	x,
		...
	)	__VA_ARGS__

Definition at line 849 of file config_options.h.

◆ STRFLDSET

#define STRFLDSET	(	type,
		...
	)	FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)

Convert a struct and a list of stringfield fields to an argument list of field offsets.

Note: Stringfields require the passing of the field manager pool, and field manager to the default stringfield option handler, so registering options that point to stringfields requires this macro to be called instead of the FLDSET macro.

Parameters

type	The type with the fields (e.g. "struct my_struct")
...	varargs The fields in the struct whose offsets are needed as arguments

Definition at line 827 of file config_options.h.

Referenced by ast_ari_config_init(), ast_bucket_init(), ast_res_pjsip_initialize_configuration(), ast_sip_initialize_sorcery_auth(), ast_sip_initialize_sorcery_domain_alias(), ast_sip_initialize_sorcery_global(), ast_sip_initialize_sorcery_location(), ast_sip_initialize_sorcery_transport(), AST_TEST_DEFINE(), load_config(), load_module(), and stir_shaken_certificate_load().

◆ VA_NARGS

#define VA_NARGS ( ... ) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)

Results in the number of arguments passed to it.

Note

Currently only up to 8, but expanding is easy. This macro basically counts commas + 1. To visualize:

* VA_NARGS(one, two, three) ->                    v
* VA_NARGS1(one, two, three,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
* VA_NARGS1( _1,  _2,    _3, _4, _5, _6, _7, _8,  N, ...       ) N -> 3
*
* Note that VA_NARGS *does not* work when there are no arguments passed. Pasting an empty
* __VA_ARGS__ with a comma like ", ##__VA_ARGS__" will delete the leading comma, but it
* does not work when __VA_ARGS__ is the first argument. Instead, 1 is returned instead of 0:
*
* VA_NARGS() ->                              v
* VA_NARGS1(  ,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
* VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8,  N) -> 1
*

Definition at line 797 of file config_options.h.

◆ VA_NARGS1

#define VA_NARGS1	(	_1,
		_2,
		_3,
		_4,
		_5,
		_6,
		_7,
		_8,
		N,
		...
	)	N

Definition at line 798 of file config_options.h.

Typedef Documentation

◆ aco_matchvalue_func

typedef 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 match.

Parameters

text	The value of the option

Return values

-1	The value is sufficient for a match
0	The value is not sufficient for a match

Definition at line 116 of file config_options.h.

◆ aco_option_handler

typedef int(* aco_option_handler) (const struct aco_option *opt, struct ast_variable *var, void *obj)

A callback function for handling a particular option.

Parameters

opt	The option being configured
var	The config variable to use to configure obj
obj	The object to be configured

Return values

0	Parsing and recording the config value succeeded
non-zero	Failure. Parsing should stop and no reload applied

Definition at line 517 of file config_options.h.

◆ aco_post_apply_config

typedef void(* aco_post_apply_config) (void)

A callback function called only if config changes have been applied.

Note: If a config file has not been edited prior to performing a reload, this callback will not be called.

Definition at line 152 of file config_options.h.

◆ aco_pre_apply_config

typedef int(* aco_pre_apply_config) (void)

A callback function to run just prior to applying config changes.

Return values

0	Success
non-zero	Failure. Changes not applied

Definition at line 145 of file config_options.h.

◆ aco_snapshot_alloc

typedef void*(* aco_snapshot_alloc) (void)

A callback function for allocating an object to hold all config objects.

Return values

NULL	error
non-NULL	a config object container

Definition at line 158 of file config_options.h.

◆ aco_type_item_alloc

typedef void*(* aco_type_item_alloc) (const char *category)

Allocate a configurable ao2 object.

Callback functions for option parsing via aco_process_config()

Parameters

category The config category the object is being generated for

Return values

NULL	error
non-NULL	a new configurable ao2 object

Definition at line 76 of file config_options.h.

◆ aco_type_item_find

typedef void*(* aco_type_item_find) (struct ao2_container *newcontainer, const char *category)

Find a item given a category and container of items.

Parameters

container	The container to search for the item
category	The category associated with the item

Return values

non-NULL	item from the container
NULL	item does not exist in container

Definition at line 84 of file config_options.h.

◆ aco_type_item_pre_process

typedef int(* aco_type_item_pre_process) (void *newitem)

Callback function that is called after a config object is initialized with defaults.

Note: This callback is called during config processing after a new config is allocated and and defaults applied but before values from the config are read. This callback could be used to merge in settings inherited from the global settings if necessary, despite that being a bad thing to do!

Parameters

newitem The newly allocated config object with defaults populated

Return values

0	succes, continue processing
non-zero	failure, stop processing

Definition at line 97 of file config_options.h.

◆ aco_type_prelink

typedef int(* aco_type_prelink) (void *newitem)

Callback function that is called after config processing, but before linking.

Note: This callback is called after config processing, but before linking the object in the config container. This callback can be used to verify that all settings make sense together, that required options have been set, etc.

Parameters

newitem The newly configured object

Return values

0	success, continue processing
non-zero	failure, stop processing

Definition at line 109 of file config_options.h.

Enumeration Type Documentation

◆ aco_category_op

enum aco_category_op

Type of category matching to perform

Enumerator
ACO_BLACKLIST	Regex based blacklist.
ACO_WHITELIST	Regex based whitelist.
ACO_BLACKLIST_EXACT	Blacklist with a single string matched with strcasecmp.
ACO_WHITELIST_EXACT	Whitelist with a single string matched with strcasecmp.
ACO_BLACKLIST_ARRAY	Blacklist with a NULL terminated array of strings matched with strcasecmp.
ACO_WHITELIST_ARRAY	Whitelist with a NULL terminated array of strings matched with strcasecmp.

Definition at line 47 of file config_options.h.

                      {
    /*! Regex based blacklist. */
    ACO_BLACKLIST = 0,
    /*! Regex based whitelist. */
    ACO_WHITELIST,
    /*! Blacklist with a single string matched with strcasecmp. */
    ACO_BLACKLIST_EXACT,
    /*! Whitelist with a single string matched with strcasecmp. */
    ACO_WHITELIST_EXACT,
    /*! Blacklist with a NULL terminated array of strings matched with strcasecmp. */
    ACO_BLACKLIST_ARRAY,
    /*! Whitelist with a NULL terminated array of strings matched with strcasecmp. */
    ACO_WHITELIST_ARRAY,
 };

◆ aco_matchtype

enum aco_matchtype

What kind of matching should be done on an option name.

Enumerator
ACO_EXACT
ACO_REGEX
ACO_PREFIX

Definition at line 63 of file config_options.h.

                    {
    ACO_EXACT = 1,
    ACO_REGEX,
    ACO_PREFIX,
 };

◆ aco_option_type

enum aco_option_type

The option types.

Note: aco_option_register takes an option type which is used to look up the handler for that type. Each non-custom type requires field names for specific types in the struct being configured. Each option below is commented with the field types, additional arguments and example usage with aco_option_register

Enumerator
OPT_ACL_T	Type for default option handler for ACLs. Note aco_option_register flags: non-zero : "permit" 0 : "deny" aco_option_register varargs: FLDSET macro with the field of type struct ast_ha . Example: {code} struct test_item { struct ast_ha ha; }; aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha)); aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha)); {code}
OPT_BOOL_T	Type for default option handler for bools (ast_true/ast_false) Note aco_option_register flags: non-zero : process via ast_true 0 : process via ast_false aco_option_register varargs: FLDSET macro with the field of type int. It is important to note that the field cannot be a bitfield. If bitfields are required, they must be set via a custom handler. Example: {code} struct test_item { int enabled; }; aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled)); {endcode}
OPT_BOOLFLAG_T	Type for default option handler for bools (ast_true/ast_false) that are stored in a flag. Note aco_option_register flags: non-zero : process via ast_true 0 : process via ast_false aco_option_register varargs: FLDSET macro with the field of type of unsigned int. The flag to set Example: {code} #define MY_TYPE_ISQUIET 1 << 4 struct test_item { unsigned int flags; }; aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET); {endcode}
OPT_CHAR_ARRAY_T	Type for default option handler for character array strings. Note aco_option_register flags: non-zero : String cannot be empty. 0 : String can be empty. aco_option_register varargs: CHARFLDSET macro with a field of type char[] Example: {code} struct test_item { char description[128]; }; aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description)); {endcode}
OPT_CODEC_T	Type for default option handler for format capabilities. Note aco_option_register flags: non-zero : This is an "allow" style option 0 : This is a "disallow" style option aco_option_register varargs: FLDSET macro with field representing a struct ast_format_cap * Example: {code} struct test_item { struct ast_format cap *cap; }; aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap)); aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap)); {endcode}
OPT_CUSTOM_T	Type for a custom (user-defined) option handler.
OPT_DOUBLE_T	Type for default option handler for doubles. Note aco_option_register flags: See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field of type double Example: struct test_item { double dub; }; {code} aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub)); {endcode}
OPT_INT_T	Type for default option handler for signed integers. Note aco_option_register flags: See flags available for use with the PARSE_INT32 type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field of type int32_t The remaining varargs for should be arguments compatible with the varargs for the ast_parse_arg function with the PARSE_INT32 type and the flags passed in the aco_option_register flags parameter. In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config contains an invalid value, it is better to let the config loading fail with warnings so that the problem is fixed by the administrator. Example: struct test_item { int32_t intopt; }; {code} aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10); {endcode}
OPT_NOOP_T	Type for a default handler that should do nothing. Note This might be useful for a "type" field that is valid, but doesn't actually need to do anything
OPT_SOCKADDR_T	Type for default handler for ast_sockaddrs. Note aco_option_register flags: See flags available for use with the PARSE_ADDR type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field being of type struct ast_sockaddr. Example: {code} struct test_item { struct ast_sockaddr addr; }; aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr)); {endcode}
OPT_STRINGFIELD_T	Type for default option handler for stringfields. Note aco_option_register flags: non-zero : String cannot be empty. 0 : String can be empty. aco_option_register varargs: STRFLDSET macro with the field being the field created by AST_STRING_FIELD Example: {code} struct test_item { AST_DECLARE_STRING_FIELDS( AST_STRING_FIELD(thing); ); }; aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing)); {endcode}
OPT_UINT_T	Type for default option handler for unsigned integers. Note aco_option_register flags: See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field of type uint32_t The remaining varargs for should be arguments compatible with the varargs for the ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the aco_option_register flags parameter. In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config contains an invalid value, it is better to let the config loading fail with warnings so that the problem is fixed by the administrator. Example: struct test_item { int32_t intopt; }; {code} aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10); {endcode}
OPT_YESNO_T	Type for default option handler for bools (ast_true/ast_false) Note aco_option_register flags: non-zero : process via ast_true 0 : process via ast_false aco_option_register varargs: FLDSET macro with the field of type int. It is important to note that the field cannot be a bitfield. If bitfields are required, they must be set via a custom handler. This is exactly the same as OPT_BOOL_T. The only difference is that when translated to a string, OPT_BOOL_T becomes "true" or "false"; OPT_YESNO_T becomes "yes" or "no". Example: {code} struct test_item { int enabled; }; aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled)); {endcode}
OPT_TIMELEN_T	Type for default option handler for time length signed integers. Note aco_option_register flags: See flags available for use with the PARSE_TIMELEN type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field of type int The remaining varargs for should be arguments compatible with the varargs for the ast_parse_arg function with the PARSE_TIMELEN type and the flags passed in the aco_option_register flags parameter. In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config contains an invalid value, it is better to let the config loading fail with warnings so that the problem is fixed by the administrator. Example: struct test_item { int timelen; }; {code} 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); {endcode}

Definition at line 259 of file config_options.h.

                      {
    /*! \brief Type for default option handler for ACLs
     * \note aco_option_register flags:
     *   non-zero : "permit"
     *   0        : "deny"
     * aco_option_register varargs:
     *   FLDSET macro with the field of type struct ast_ha *.
     *
     * Example:
     * {code}
     * struct test_item {
     *     struct ast_ha *ha;
     * };
     * aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
     * aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
     * {code}
     */
    OPT_ACL_T,
 
    /*! \brief Type for default option handler for bools (ast_true/ast_false)
     * \note aco_option_register flags:
     *   non-zero : process via ast_true
     *   0        : process via ast_false
     * aco_option_register varargs:
     *   FLDSET macro with the field of type int. It is important to note that the field
     *   cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
     *
     * Example:
     * {code}
     * struct test_item {
     *     int enabled;
     * };
     * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
     * {endcode}
     */
    OPT_BOOL_T,
 
    /*! \brief Type for default option handler for bools (ast_true/ast_false) that are stored in a flag
     * \note aco_option_register flags:
     *   non-zero : process via ast_true
     *   0        : process via ast_false
     * aco_option_register varargs:
     *   FLDSET macro with the field of type of unsigned int.
     *   The flag to set
     *
     * Example:
     * {code}
     * #define MY_TYPE_ISQUIET    1 << 4
     * struct test_item {
     *     unsigned int flags;
     * };
     * aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET);
     * {endcode}
     */
    OPT_BOOLFLAG_T,
 
    /*! \brief Type for default option handler for character array strings
     * \note aco_option_register flags:
     *   non-zero : String cannot be empty.
     *   0        : String can be empty.
     * \note aco_option_register varargs:
     *   CHARFLDSET macro with a field of type char[]
     *
     * Example:
     * {code}
     * struct test_item {
     *     char description[128];
     * };
     * aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description));
     * {endcode}
     */
    OPT_CHAR_ARRAY_T,
 
    /*! \brief Type for default option handler for format capabilities
     * \note aco_option_register flags:
     *   non-zero : This is an "allow" style option
     *   0        : This is a "disallow" style option
     * aco_option_register varargs:
     *   FLDSET macro with field representing a struct ast_format_cap *
     *
     * Example:
     * {code}
     * struct test_item {
     *     struct ast_format cap *cap;
     * };
     * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
     * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
     * {endcode}
     */
    OPT_CODEC_T,
 
    /*! \brief Type for a custom (user-defined) option handler */
    OPT_CUSTOM_T,
 
    /*! \brief Type for default option handler for doubles
     *
     * \note aco_option_register flags:
     *   See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function
     * aco_option_register varargs:
     *   FLDSET macro with the field of type double
     *
     * Example:
     * struct test_item {
     *     double dub;
     * };
     * {code}
     * aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
     * {endcode}
     */
    OPT_DOUBLE_T,
 
    /*! \brief Type for default option handler for signed integers
     *
     * \note aco_option_register flags:
     *   See flags available for use with the PARSE_INT32 type for the ast_parse_arg function
     * aco_option_register varargs:
     *   FLDSET macro with the field of type int32_t
     *   The remaining varargs for should be arguments compatible with the varargs for the
     *   ast_parse_arg function with the PARSE_INT32 type and the flags passed in the
     *   aco_option_register flags parameter.
     *
     * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
     * contains an invalid value, it is better to let the config loading fail with warnings so that
     * the problem is fixed by the administrator.
     *
     * Example:
     * struct test_item {
     *     int32_t intopt;
     * };
     * {code}
     * aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
     * {endcode}
     */
    OPT_INT_T,
 
    /*! \brief Type for a default handler that should do nothing
     *
     * \note This might be useful for a "type" field that is valid, but doesn't
     * actually need to do anything
     */
    OPT_NOOP_T,
 
    /*! \brief Type for default handler for ast_sockaddrs
     *
     * \note aco_option_register flags:
     *   See flags available for use with the PARSE_ADDR type for the ast_parse_arg function
     * aco_option_register varargs:
     *   FLDSET macro with the field being of type struct ast_sockaddr.
     *
     * Example:
     * {code}
     * struct test_item {
     *     struct ast_sockaddr addr;
     * };
     * aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
     * {endcode}
     */
    OPT_SOCKADDR_T,
 
    /*! \brief Type for default option handler for stringfields
     * \note aco_option_register flags:
     *   non-zero : String cannot be empty.
     *   0        : String can be empty.
     * aco_option_register varargs:
     *   STRFLDSET macro with the field being the field created by AST_STRING_FIELD
     *
     * Example:
     * {code}
     * struct test_item {
     *     AST_DECLARE_STRING_FIELDS(
     *         AST_STRING_FIELD(thing);
     *     );
     * };
     * aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing));
     * {endcode}
     */
    OPT_STRINGFIELD_T,
 
    /*! \brief Type for default option handler for unsigned integers
     *
     * \note aco_option_register flags:
     *   See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function
     * aco_option_register varargs:
     *   FLDSET macro with the field of type uint32_t
     *   The remaining varargs for should be arguments compatible with the varargs for the
     *   ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the
     *   aco_option_register flags parameter.
     *
     * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
     * contains an invalid value, it is better to let the config loading fail with warnings so that
     * the problem is fixed by the administrator.
     *
     * Example:
     * struct test_item {
     *     int32_t intopt;
     * };
     * {code}
     * aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
     * {endcode}
     */
    OPT_UINT_T,
 
    /*! \brief Type for default option handler for bools (ast_true/ast_false)
     * \note aco_option_register flags:
     *   non-zero : process via ast_true
     *   0        : process via ast_false
     * aco_option_register varargs:
     *   FLDSET macro with the field of type int. It is important to note that the field
     *   cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
     *
     * This is exactly the same as OPT_BOOL_T. The only difference is that when
     * translated to a string, OPT_BOOL_T becomes "true" or "false"; OPT_YESNO_T becomes
     * "yes" or "no".
     *
     * Example:
     * {code}
     * struct test_item {
     *     int enabled;
     * };
     * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled));
     * {endcode}
     */
    OPT_YESNO_T,
 
    /*! \brief Type for default option handler for time length signed integers
     *
     * \note aco_option_register flags:
     *   See flags available for use with the PARSE_TIMELEN type for the ast_parse_arg function
     * aco_option_register varargs:
     *   FLDSET macro with the field of type int
     *   The remaining varargs for should be arguments compatible with the varargs for the
     *   ast_parse_arg function with the PARSE_TIMELEN type and the flags passed in the
     *   aco_option_register flags parameter.
     *
     * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
     * contains an invalid value, it is better to let the config loading fail with warnings so that
     * the problem is fixed by the administrator.
     *
     * Example:
     * struct test_item {
     *     int timelen;
     * };
     * {code}
     * 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);
     * {endcode}
     */
    OPT_TIMELEN_T,
 
 };

◆ aco_process_status

enum aco_process_status

Return values for the aco_process functions.

Enumerator
ACO_PROCESS_OK	The config was processed and applied.
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.

Definition at line 524 of file config_options.h.

                         {
    ACO_PROCESS_OK,        /*!< \brief The config was processed and applied */
    ACO_PROCESS_UNCHANGED, /*!< \brief The config had not been edited and no changes applied */
    ACO_PROCESS_ERROR,     /*!< \brief Their was an error and no changes were applied */
 };

◆ aco_type_t

enum aco_type_t

Enumerator
ACO_GLOBAL
ACO_ITEM
ACO_IGNORE

Definition at line 40 of file config_options.h.

                 {
    ACO_GLOBAL,
    ACO_ITEM,
    ACO_IGNORE,
 };

Function Documentation

◆ __aco_option_register()

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

Note: this should probably only be called by one of the aco_option_register* macros

Parameters

info	The aco_info holding this module's config information
name	The name of the option
match_type
types	An array of valid option types for matching categories to the correct struct type
default_val	The default value of the option in the same format as defined in a config file
type	The option type (only for default handlers)
handler	The handler function for the option (only for non-default types)
flags	a type specific flags, stored in the option and available to the handler
no_doc	if non-zero, this option should not have documentation
argc	The number for variadic arguments
...	field offsets to store for default handlers

Return values

0	success
-1	failure

Definition at line 300 of file config_options.c.

References ACO_REGEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, aco_option::argc, aco_option::args, ast_config_option_default_handler(), ast_log, build_regex(), config_option_destroy(), aco_option::default_val, aco_option::flags, handler(), aco_option::handler, link_option_to_types(), LOG_ERROR, aco_option::match_type, aco_option::name, name, aco_option::name_regex, aco_option::no_doc, OPT_CUSTOM_T, tmp(), and aco_option::type.

Referenced by __ast_sorcery_object_field_register(), and ast_sorcery_object_fields_register().

 {
    struct aco_option *opt;
    va_list ap;
    int tmp;
 
    /* Custom option types require a handler */
    if (!handler && kind == OPT_CUSTOM_T) {
       return -1;
    }
 
    if (!(types && types[0])) {
       return -1;
    }
 
    opt = ao2_alloc_options(sizeof(*opt) + argc * sizeof(opt->args[0]),
       config_option_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!opt) {
       return -1;
    }
 
    if (matchtype == ACO_REGEX && !(opt->name_regex = build_regex(name))) {
       ao2_ref(opt, -1);
       return -1;
    }
 
    va_start(ap, argc);
    for (tmp = 0; tmp < argc; tmp++) {
       opt->args[tmp] = va_arg(ap, size_t);
    }
    va_end(ap);
 
    opt->name = name;
    opt->match_type = matchtype;
    opt->default_val = default_val;
    opt->type = kind;
    opt->handler = handler;
    opt->flags = flags;
    opt->argc = argc;
    opt->no_doc = no_doc;
 
    if (!opt->handler && !(opt->handler = ast_config_option_default_handler(opt->type))) {
       /* This should never happen */
       ast_log(LOG_ERROR, "No handler provided, and no default handler exists for type %u\n", opt->type);
       ao2_ref(opt, -1);
       return -1;
    };
 
    if (link_option_to_types(info, types, opt)) {
       ao2_ref(opt, -1);
       return -1;
    }
 
    return 0;
 }

◆ aco_info_destroy()

void aco_info_destroy ( struct aco_info * info )

Destroy an initialized aco_info struct.

Parameters

info	The address of the aco_info struct to destroy

Definition at line 910 of file config_options.c.

References ast_free, aco_info::files, aco_info::internal, internal_file_types_destroy(), and NULL.

Referenced by aco_info_init(), ast_ari_config_destroy(), ast_ari_config_init(), AST_TEST_DEFINE(), cdr_engine_shutdown(), conf_destroy_config(), destroy_config(), load_module(), sorcery_object_type_destructor(), stasis_cleanup(), unload_features_config(), and unload_module().

 {
    int x;
    /* It shouldn't be possible for internal->pending to be in use when this is called because
     * of the locks in loader.c around reloads and unloads and the fact that internal->pending
     * only exists while those locks are held */
    ast_free(info->internal);
    info->internal = NULL;
 
    for (x = 0; info->files[x]; x++) {
       internal_file_types_destroy(info->files[x]);
    }
 }

◆ aco_info_init()

int aco_info_init ( struct aco_info * info )

Initialize an aco_info structure.

Note: aco_info_destroy must be called if this succeeds

Parameters

info	The address of an aco_info struct to initialize

Return values

0	Success
non-zero	Failure

Definition at line 877 of file config_options.c.

References ACO_IGNORE, aco_info_destroy(), ast_calloc, aco_type::category, aco_type::category_match, error(), make_ari_stubs::file, aco_info::files, aco_type::hidden, aco_info::hidden, aco_info::internal, internal_type_init(), aco_type::matchfield, aco_type::matchvalue, aco_info::module, aco_type::name, type, aco_type::type, aco_file::types, and xmldoc_update_config_type().

Referenced by __ast_sorcery_object_register(), ast_ari_config_init(), AST_TEST_DEFINE(), conf_load_config(), load_config(), load_module(), process_config(), and stasis_init().

 {
    size_t x = 0, y = 0;
    struct aco_file *file;
    struct aco_type *type;
 
    if (!(info->internal = ast_calloc(1, sizeof(*info->internal)))) {
       return -1;
    }
 
    while ((file = info->files[x++])) {
       while ((type = file->types[y++])) {
          if (internal_type_init(type)) {
             goto error;
          }
 #ifdef AST_XML_DOCS
          if (!info->hidden &&
             !type->hidden &&
             type->type != ACO_IGNORE &&
             xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match)) {
             goto error;
          }
 #endif /* AST_XML_DOCS */
       }
       y = 0;
    }
 
    return 0;
 error:
    aco_info_destroy(info);
    return -1;
 }

◆ aco_option_container_alloc()

struct ao2_container* aco_option_container_alloc ( void )

Allocate a container to hold config options.

Definition at line 406 of file config_options.c.

References AO2_ALLOC_OPT_LOCK_MUTEX, ao2_container_alloc_hash, CONFIG_OPT_BUCKETS, config_opt_cmp(), config_opt_hash(), and NULL.

Referenced by internal_type_init().

 {
    return ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0, CONFIG_OPT_BUCKETS,
       config_opt_hash, NULL, config_opt_cmp);
 }

◆ aco_option_get_argument()

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.

Parameters

option	Pointer to the aco_option struct
arg	Argument number

Return values

position of the argument

Definition at line 248 of file config_options.c.

References aco_option::args.

Referenced by timeval_str2struct().

 {
    return option->args[position];
 }

◆ aco_option_get_flags()

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.

Since: 12

Parameters

option Pointer to the aco_option struct

Return values

value of the flags on the config option

Definition at line 243 of file config_options.c.

References aco_option::flags.

Referenced by option_handler_parkedfeature().

 {
    return option->flags;
 }

◆ aco_option_register_deprecated()

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.

Parameters

info	A pointer to the aco_info struct
name	The name of the deprecated option
types	An array of valid option types for matching categories to the correct struct type
aliased_to	The name of the option that this deprecated option matches to

Return values

0	Success
-1	Failure

Definition at line 217 of file config_options.c.

References ACO_EXACT, aco_option::aliased_to, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, ast_strlen_zero, config_option_destroy(), aco_option::deprecated, link_option_to_types(), aco_option::match_type, aco_option::name, and name.

Referenced by AST_TEST_DEFINE().

 {
    struct aco_option *opt;
 
    if (!info || ast_strlen_zero(name) || ast_strlen_zero(aliased_to)) {
       return -1;
    }
 
    opt = ao2_alloc_options(sizeof(*opt), config_option_destroy, AO2_ALLOC_OPT_LOCK_NOLOCK);
    if (!opt) {
       return -1;
    }
 
    opt->name = name;
    opt->aliased_to = aliased_to;
    opt->deprecated = 1;
    opt->match_type = ACO_EXACT;
 
    if (link_option_to_types(info, types, opt)) {
       ao2_ref(opt, -1);
       return -1;
    }
 
    return 0;
 }

◆ aco_pending_config()

void* aco_pending_config ( struct aco_info * info )

Get pending config changes.

Note: This will most likely be called from the pre_apply_config callback function

Parameters

info	An initialized aco_info

Return values

NULL	error
non-NULL	A pointer to the user-defined config object with un-applied changes

Definition at line 103 of file config_options.c.

References ast_log, aco_info::internal, LOG_ERROR, NULL, and aco_info_internal::pending.

Referenced by cel_pre_apply_config(), configure_parking_extensions(), features_pre_apply_config(), hepv3_config_pre_apply(), prometheus_config_pre_apply(), udptl_pre_apply_config(), unbound_config_preapply_callback(), verify_default_parking_lot(), and verify_default_profiles().

 {
    if (!(info && info->internal)) {
       ast_log(LOG_ERROR, "This may not be called without an initialized aco_info!\n");
       return NULL;
    }
    return info->internal->pending;
 }

◆ aco_process_ast_config()

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.

Parameters

info	The aco_info to be used for handling the config
file	The file attached to aco_info that the config represents
cfg	A pointer to a loaded ast_config to parse

Return values

ACO_PROCESS_OK	Success
ACO_PROCESS_ERROR	Failure

Definition at line 617 of file config_options.c.

References ACO_PROCESS_ERROR, ACO_PROCESS_OK, ao2_cleanup, apply_config(), ast_log, error(), aco_file::filename, aco_info::internal, internal_process_ast_config(), LOG_ERROR, NULL, aco_info_internal::pending, aco_info::pre_apply_config, and aco_info::snapshot_alloc.

 {
    if (!info->internal) {
       ast_log(LOG_ERROR, "Attempt to process %s with uninitialized aco_info\n", file->filename);
       return ACO_PROCESS_ERROR;
    }
 
    if (!(info->internal->pending = info->snapshot_alloc())) {
       ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", file->filename);
       goto error;
    }
 
    if (internal_process_ast_config(info, file, cfg)) {
       goto error;
    }
 
    if (info->pre_apply_config && info->pre_apply_config()) {
       goto error;
    }
 
    if (apply_config(info)) {
       goto error;
    };
 
    ao2_cleanup(info->internal->pending);
    info->internal->pending = NULL;
    return ACO_PROCESS_OK;
 
 error:
    ao2_cleanup(info->internal->pending);
    info->internal->pending = NULL;
 
    return ACO_PROCESS_ERROR;
 }

◆ aco_process_category_options()

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.

Parameters

type	The aco_type with the options for parsing
cfg	The ast_config being parsed
cat	The config category being parsed
obj	The user-defined config object that will store the parsed config items

Return values

0	Success
-1	Failure

Definition at line 805 of file config_options.c.

References aco_process_var(), ast_variable_browse(), ast_variable::next, and var.

Referenced by process_category().

 {
    struct ast_variable *var;
 
    for (var = ast_variable_browse(cfg, cat); var; var = var->next) {
       if (aco_process_var(type, cat, var, obj)) {
          return -1;
       }
    }
 
    return 0;
 }

◆ aco_process_config()

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.

Parameters

info	The config_options_info to be used for handling the config
reload	Non-zero if this is for a reload.

Return values

ACO_PROCESS_OK	Success
ACO_PROCESS_ERROR	Failure
ACO_PROCESS_UNCHANGED	No change due to unedited config file

Definition at line 652 of file config_options.c.

References ACO_GLOBAL, ACO_IGNORE, ACO_PROCESS_ERROR, ACO_PROCESS_OK, ACO_PROCESS_UNCHANGED, aco_set_defaults(), aco_file::alias, ao2_cleanup, apply_config(), ast_clear_flag, ast_config_destroy(), ast_config_load, ast_debug, ast_log, aco_type::category, CONFIG_FLAG_FILEUNCHANGED, CONFIG_STATUS_FILEINVALID, CONFIG_STATUS_FILEMISSING, CONFIG_STATUS_FILEUNCHANGED, end, make_ari_stubs::file, aco_file::filename, aco_info::files, aco_info::internal, internal_process_ast_config(), aco_type::item_offset, LOG_ERROR, match(), aco_info::module, NULL, aco_info_internal::pending, aco_info::post_apply_config, aco_info::pre_apply_config, aco_info::snapshot_alloc, aco_type::type, and aco_file::types.

Referenced by __ast_udptl_reload(), AST_TEST_DEFINE(), conf_load_config(), conf_reload_config(), load_config(), load_module(), process_config(), reload(), reload_features_config(), reload_module(), and stasis_init().

 {
    struct ast_config *cfg;
    struct ast_flags cfg_flags = { reload ? CONFIG_FLAG_FILEUNCHANGED : 0, };
    int res = ACO_PROCESS_OK;
    int file_count = 0;
    struct aco_file *file;
 
    if (!info->internal) {
       ast_log(LOG_ERROR, "Attempting to process uninitialized aco_info\n");
       return ACO_PROCESS_ERROR;
    }
 
    if (!(info->files[0])) {
       ast_log(LOG_ERROR, "No filename given, cannot proceed!\n");
       return ACO_PROCESS_ERROR;
    }
 
    if (!(info->internal->pending = info->snapshot_alloc())) {
       ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", info->module);
       return ACO_PROCESS_ERROR;
    }
 
    while (res != ACO_PROCESS_ERROR && (file = info->files[file_count++])) {
       const char *filename = file->filename;
       struct aco_type *match;
       int i;
 
       /* set defaults for global objects */
       for (i = 0, match = file->types[i]; match; match = file->types[++i]) {
          void **field = info->internal->pending + match->item_offset;
 
          if (match->type == ACO_IGNORE) {
             continue;
          }
 
          if (match->type != ACO_GLOBAL || !*field) {
             continue;
          }
 
          if (aco_set_defaults(match, match->category, *field)) {
             ast_log(LOG_ERROR, "In %s: Setting defaults for %s failed\n", file->filename, match->category);
             res = ACO_PROCESS_ERROR;
             break;
          }
       }
 
       if (res == ACO_PROCESS_ERROR) {
          break;
       }
 
 try_alias:
       cfg = ast_config_load(filename, cfg_flags);
       if (!cfg || cfg == CONFIG_STATUS_FILEMISSING) {
          if (file->alias && strcmp(file->alias, filename)) {
             filename = file->alias;
             goto try_alias;
          }
          ast_log(LOG_ERROR, "Unable to load config file '%s'\n", file->filename);
          res = ACO_PROCESS_ERROR;
          break;
       } else if (cfg == CONFIG_STATUS_FILEUNCHANGED) {
          ast_debug(1, "%s was unchanged\n", file->filename);
          res = ACO_PROCESS_UNCHANGED;
          continue;
       } else if (cfg == CONFIG_STATUS_FILEINVALID) {
          ast_log(LOG_ERROR, "Contents of %s are invalid and cannot be parsed\n",
             file->filename);
          res = ACO_PROCESS_ERROR;
          break;
       }
 
       /* A file got loaded. */
       if (reload) {
          /* Must do any subsequent file loads unconditionally. */
          reload = 0;
          ast_clear_flag(&cfg_flags, CONFIG_FLAG_FILEUNCHANGED);
 
          if (file_count != 1) {
             /*
              * Must restart loading to load all config files since a file
              * after the first one changed.
              */
             file_count = 0;
          } else {
             res = internal_process_ast_config(info, file, cfg);
          }
       } else {
          res = internal_process_ast_config(info, file, cfg);
       }
       ast_config_destroy(cfg);
    }
 
    if (res != ACO_PROCESS_OK) {
       goto end;
    }
 
    if (info->pre_apply_config && info->pre_apply_config()) {
       res = ACO_PROCESS_ERROR;
       goto end;
    }
 
    if (apply_config(info)) {
       res = ACO_PROCESS_ERROR;
       goto end;
    }
 
    if (info->post_apply_config) {
       info->post_apply_config();
    }
 
 end:
    ao2_cleanup(info->internal->pending);
    info->internal->pending = NULL;
 
    return res;
 }

◆ aco_process_var()

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.

Note: This function can be used to build up an object by repeatedly passing in the config variable name and values that would be found in a config file. This can be useful if the object is to be populated by a dialplan function, for example.

Parameters

type	The aco_type associated with the object
cat	The category to use
var	A variable to apply to the object
obj	A pointer to the object to be configured

Return values

0	Success
-1	Failure

Definition at line 769 of file config_options.c.

References aco_option_find(), aco_option::aliased_to, ao2_cleanup, ao2_ref, ast_log, ast_strdupa, ast_strlen_zero, aco_option::deprecated, aco_option::doc_unavailable, ast_variable::file, aco_option::handler, ast_variable::lineno, LOG_ERROR, LOG_WARNING, ast_variable::name, aco_type::name, RAII_VAR, and ast_variable::value.

Referenced by aco_process_category_options(), ast_sorcery_objectset_apply(), and func_confbridge_helper().

 {
    RAII_VAR(struct aco_option *, opt, aco_option_find(type, var->name), ao2_cleanup);
    if (opt && opt->deprecated && !ast_strlen_zero(opt->aliased_to)) {
       const char *alias = ast_strdupa(opt->aliased_to);
       ast_log(LOG_WARNING, "At line %d of %s option '%s' is deprecated. Use '%s' instead\n", var->lineno, var->file, var->name, alias);
       ao2_ref(opt, -1);
       opt = aco_option_find(type, alias);
    }
 
    if (!opt) {
       ast_log(LOG_ERROR, "Could not find option suitable for category '%s' named '%s' at line %d of %s\n", cat, var->name, var->lineno, var->file);
       return -1;
    }
 
    if (!opt->handler) {
       /* It should be impossible for an option to not have a handler */
       ast_log(LOG_ERROR, "BUG! Somehow a config option for %s/%s was created with no handler!\n", cat, var->name);
       return -1;
    }
 
 #ifdef AST_DEVMODE
    if (opt->doc_unavailable) {
       ast_log(LOG_ERROR, "Config option '%s' of type '%s' is not completely documented and can not be set\n", var->name, type->name);
       return -1;
    }
 #endif
 
    if (opt->handler(opt, var, obj)) {
       ast_log(LOG_ERROR, "Error parsing %s=%s at line %d of %s\n", var->name, var->value, var->lineno, var->file);
       return -1;
    }
 
    return 0;
 }

◆ aco_set_defaults()

int aco_set_defaults	(	struct aco_type *	type,
		const char *	category,
		void *	obj
	)

Set all default options of obj.

Parameters

type	The aco_type with the options
category	The configuration category from which obj is being configured
obj	The object being configured

Return values

0	Success
-1	Failure

Definition at line 924 of file config_options.c.

References ao2_iterator_destroy(), ao2_iterator_init(), ao2_iterator_next, ao2_ref, ast_log, ast_strlen_zero, ast_variable_new, ast_variables_destroy(), aco_option::default_val, aco_option::handler, aco_type::internal, LOG_ERROR, aco_option::name, ast_variable::name, NULL, aco_type_internal::opts, RAII_VAR, and ast_variable::value.

Referenced by __ast_udptl_reload(), aco_process_config(), ast_sorcery_alloc(), conf_alloc(), load_config(), load_module(), process_category(), process_config(), stasis_init(), unbound_config_apply_default(), verify_default_parking_lot(), and verify_default_profiles().

 {
    struct aco_option *opt;
    struct ao2_iterator iter;
 
    if (!type->internal) {
       return -1;
    }
 
    iter = ao2_iterator_init(type->internal->opts, 0);
 
    while ((opt = ao2_iterator_next(&iter))) {
       RAII_VAR(struct ast_variable *, var, NULL, ast_variables_destroy);
 
       if (ast_strlen_zero(opt->default_val)) {
          ao2_ref(opt, -1);
          continue;
       }
       if (!(var = ast_variable_new(opt->name, opt->default_val, ""))) {
          ao2_ref(opt, -1);
          ao2_iterator_destroy(&iter);
          return -1;
       }
       if (opt->handler(opt, var, obj)) {
          ast_log(LOG_ERROR, "Unable to set default for %s, %s=%s\n", category, var->name, var->value);
          ao2_ref(opt, -1);
          ao2_iterator_destroy(&iter);
          return -1;
       }
       ao2_ref(opt, -1);
    }
    ao2_iterator_destroy(&iter);
 
    return 0;
 }

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ACO_FILES

◆ aco_option_register

◆ aco_option_register_custom

◆ aco_option_register_custom_nodoc

◆ ACO_TYPES

◆ ARGIFY

◆ ARGMAP

◆ ARGMAP_

◆ ARGMAP_1

◆ ARGMAP_2

◆ ARGMAP_3

◆ ARGMAP_4

◆ ARGMAP_5

◆ ARGMAP_6

◆ ARGMAP_7

◆ ARGMAP_8

◆ CHARFLDSET

◆ CONFIG_INFO_CORE

◆ CONFIG_INFO_STANDARD

◆ CONFIG_INFO_TEST

◆ FLDSET

◆ FLDSET1

◆ PASTE

◆ PASTE1

◆ POPPED

◆ POPPED1

◆ STRFLDSET

◆ VA_NARGS

◆ VA_NARGS1

Typedef Documentation

◆ aco_matchvalue_func

◆ aco_option_handler

◆ aco_post_apply_config

◆ aco_pre_apply_config

◆ aco_snapshot_alloc

◆ aco_type_item_alloc

◆ aco_type_item_find

◆ aco_type_item_pre_process

◆ aco_type_prelink

Enumeration Type Documentation

◆ aco_category_op

◆ aco_matchtype

◆ aco_option_type

◆ aco_process_status

◆ aco_type_t

Function Documentation

◆ __aco_option_register()

◆ aco_info_destroy()

◆ aco_info_init()

◆ aco_option_container_alloc()

◆ aco_option_get_argument()

◆ aco_option_get_flags()

◆ aco_option_register_deprecated()

◆ aco_pending_config()

◆ aco_process_ast_config()

◆ aco_process_category_options()

◆ aco_process_config()

◆ aco_process_var()

◆ aco_set_defaults()