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...
Defines
#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, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
	Register a config option.
#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);
	Register a config option.
#define	ACO_TYPES(...) { __VA_ARGS__, NULL, }
	A helper macro to ensure that aco_info types always have a sentinel.
#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.
#define	CONFIG_INFO_STANDARD(name, arr, alloc,...)
	Declare an aco_info struct with default module and preload values.
#define	FLDSET(type,...) FLDSET1(type, ##__VA_ARGS__)
#define	FLDSET1(type,...) POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))
#define	POPPED(...) POPPED1(__VA_ARGS__)
	A list of arguments without the first argument.
#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.
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.
typedef int(*	aco_option_handler )(const struct aco_option opt, struct ast_variable var, void *obj)
	A callback function for handling a particular option.
typedef void(*	aco_post_apply_config )(void)
	A callback function called only if config changes have been applied.
typedef int(*	aco_pre_apply_config )(void)
	A callback function to run just prior to applying config changes.
typedef void (	aco_snapshot_alloc )(void)
	A callback function for allocating an object to hold all config objects.
typedef void (	aco_type_item_alloc )(const char *category)
	Allocate a configurable ao2 object.
typedef void (	aco_type_item_find )(struct ao2_container newcontainer, const char category)
	Find a item given a category and container of items.
typedef int(*	aco_type_item_pre_process )(void *newitem)
	Callback function that is called after a config object is initialized with defaults.
typedef int(*	aco_type_prelink )(void *newitem)
	Callback function that is called after config processing, but before linking.
Enumerations
enum	aco_category_op { ACO_BLACKLIST = 0, ACO_WHITELIST }
	Whether a category regex is a blackist or a whitelist. More...
enum	aco_matchtype { ACO_EXACT = 1, ACO_REGEX }
	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 }
	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 }
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, size_t argc,...)
	register a config option
void	aco_info_destroy (struct aco_info *info)
	Destroy an initialized aco_info struct.
int	aco_info_init (struct aco_info *info)
	Initialize an aco_info structure.
struct ao2_container *	aco_option_container_alloc (void)
	Allocate a container to hold config options.
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.
void *	aco_pending_config (struct aco_info *info)
	Get pending config changes.
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.
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.
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.
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_set_defaults (struct aco_type type, const char category, void *obj)
	Set all default options of obj.

Detailed Description

Configuration option-handling.

Author:: Terry Wilson <twilson@digium.com>

Definition in file config_options.h.

Define Documentation

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

Definition at line 166 of file config_options.h.

#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, 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
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	type specific flags, stored in the option and available to the handler

Return values:

0	Success
-1	Failure

Definition at line 539 of file config_options.h.

Referenced by ast_named_acl_init(), ast_udptl_init(), and load_module().

#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);

Register a config option.

Parameters:

info	A pointer to the aco_info struct
name	The name of the option
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 553 of file config_options.h.

Referenced by ast_udptl_init(), and load_module().

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

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

Definition at line 165 of file config_options.h.

#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 705 of file config_options.h.

#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
fn	The filename of the config
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 198 of file config_options.h.

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

Definition at line 686 of file config_options.h.

Referenced by ast_named_acl_init(), ast_udptl_init(), and load_module().

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

Definition at line 687 of file config_options.h.

#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. varags A list of arguments

POPPED(a, b, c) -> b, c

Definition at line 717 of file config_options.h.

#define POPPED1	(	x,
		...
	)	__VA_ARGS__

Definition at line 718 of file config_options.h.

#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 697 of file config_options.h.

Referenced by load_module().

Typedef Documentation

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 104 of file config_options.h.

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 436 of file config_options.h.

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 138 of file config_options.h.

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 131 of file config_options.h.

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 144 of file config_options.h.

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 64 of file config_options.h.

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 72 of file config_options.h.

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 85 of file config_options.h.

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 97 of file config_options.h.

Enumeration Type Documentation

enum aco_category_op

Whether a category regex is a blackist or a whitelist.

Enumerator:

ACO_BLACKLIST
ACO_WHITELIST

Definition at line 46 of file config_options.h.

                     {
   ACO_BLACKLIST = 0,
   ACO_WHITELIST,
};

enum aco_matchtype

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

Enumerator:

ACO_EXACT
ACO_REGEX

Definition at line 52 of file config_options.h.

                   {
   ACO_EXACT = 1,
   ACO_REGEX,
};

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 arrays. 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, CHARFLDSET(struct test_item, description)); {endcode}
OPT_CODEC_T	Type for default option handler for codec preferences/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 fields representing a struct ast_codec_pref and a struct ast_format_cap * Example: {code} struct test_item { struct ast_codec_pref pref; 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, pref, cap)); aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, pref, 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, 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: none 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}

Definition at line 227 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 arrays
    * \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, CHARFLDSET(struct test_item, description));
    * {endcode}
    */
   OPT_CHAR_ARRAY_T,

   /*! \brief Type for default option handler for codec preferences/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 fields representing a struct ast_codec_pref and a struct ast_format_cap *
    *
    * Example:
    * {code}
    * struct test_item {
    *     struct ast_codec_pref pref;
    *     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, pref, cap));
    * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, pref, 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, 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:
    *   none
    * 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,
};

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 443 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 */
};

enum aco_type_t

Enumerator:

ACO_GLOBAL
ACO_ITEM

Definition at line 40 of file config_options.h.

                {
   ACO_GLOBAL,
   ACO_ITEM,
};

Function Documentation

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,
		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
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	type specific flags, stored in the option and available to the handler
argc	The number for variadic arguments
...	field offsets to store for default handlers

Return values:

0	success
-1	failure

Definition at line 193 of file config_options.c.

References ACO_REGEX, ao2_alloc, 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, aco_option::handler, link_option_to_types(), LOG_ERROR, aco_option::match_type, name, aco_option::name, aco_option::name_regex, OPT_CUSTOM_T, and aco_option::type.

{
   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;
   }

   if (!(opt = ao2_alloc(sizeof(*opt) + argc * sizeof(opt->args[0]), config_option_destroy))) {
      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;

   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 %d\n", opt->type);
      ao2_ref(opt, -1);
      return -1;
   };

   if (link_option_to_types(types, opt)) {
      ao2_ref(opt, -1);
      return -1;
   }

   return 0;
}

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 690 of file config_options.c.

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

Referenced by aco_info_init(), ast_named_acl_init(), load_module(), named_acl_cleanup(), udptl_shutdown(), 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]);
   }
}

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 668 of file config_options.c.

References aco_info_destroy(), ast_calloc, aco_info::files, aco_info::internal, internal_type_init(), and aco_file::types.

Referenced by ast_named_acl_init(), ast_udptl_init(), and load_module().

{
   size_t x, y;

   if (!(info->internal = ast_calloc(1, sizeof(*info->internal)))) {
      return -1;
   }

   for (x = 0; info->files[x]; x++) {
      for (y = 0; info->files[x]->types[y]; y++) {
         if (internal_type_init(info->files[x]->types[y])) {
            goto error;
         }
      }
   }

   return 0;
error:
   aco_info_destroy(info);
   return -1;
}

struct ao2_container* aco_option_container_alloc ( void ) [read]

Allocate a container to hold config options.

Definition at line 293 of file config_options.c.

References ao2_container_alloc, CONFIG_OPT_BUCKETS, config_opt_cmp(), and config_opt_hash().

Referenced by internal_type_init().

{
   return ao2_container_alloc(CONFIG_OPT_BUCKETS, config_opt_hash, config_opt_cmp);
}

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 168 of file config_options.c.

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

{
   struct aco_option *opt;

   if (!info || ast_strlen_zero(name) || ast_strlen_zero(aliased_to)) {
      return -1;
   }

   if (!(opt = ao2_alloc(sizeof(*opt), config_option_destroy))) {
      return -1;
   }

   opt->name = name;
   opt->aliased_to = aliased_to;
   opt->deprecated = 1;
   opt->match_type = ACO_EXACT;

   if (link_option_to_types(types, opt)) {
      ao2_ref(opt, -1);
      return -1;
   }

   return 0;
}

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 73 of file config_options.c.

References ast_log(), aco_info::internal, LOG_ERROR, and aco_info_internal::pending.

Referenced by udptl_pre_apply_config().

{
   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;
}

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
reload	Whether or not this is a reload

Return values:

ACO_PROCESS_OK	Success
ACO_PROCESS_ERROR	Failure

Definition at line 447 of file config_options.c.

References ACO_PROCESS_ERROR, ACO_PROCESS_OK, ao2_cleanup, apply_config(), ast_log(), aco_file::filename, aco_info::internal, internal_process_ast_config(), LOG_ERROR, 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);
      goto 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);
   return ACO_PROCESS_OK;

error:
   ao2_cleanup(info->internal->pending);
   return ACO_PROCESS_ERROR;
}

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 606 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;
}

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	Whether or not this is 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 479 of file config_options.c.

References ACO_GLOBAL, ACO_PROCESS_ERROR, ACO_PROCESS_OK, ACO_PROCESS_UNCHANGED, aco_set_defaults(), aco_file::alias, ao2_cleanup, apply_config(), 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, aco_file::filename, aco_info::files, aco_info::internal, internal_process_ast_config(), aco_type::item_offset, LOG_ERROR, match(), aco_info::module, 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_named_acl_init(), ast_named_acl_reload(), load_module(), reload(), and reload_module().

{
   struct ast_config *cfg;
   struct ast_flags cfg_flags = { reload ? CONFIG_FLAG_FILEUNCHANGED : 0, };
   int res = ACO_PROCESS_OK, x = 0;
   struct aco_file *file;

   if (!(info->files[0])) {
      ast_log(LOG_ERROR, "No filename given, cannot proceed!\n");
      return ACO_PROCESS_ERROR;
   }

   if (!info->internal) {
      ast_log(LOG_ERROR, "Attempting to process uninitialized aco_info\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[x++])) {
      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_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:
      if (!(cfg = ast_config_load(filename, cfg_flags))) {
         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;
      } else if (cfg == CONFIG_STATUS_FILEMISSING) {
         if (file->alias && strcmp(file->alias, filename)) {
            filename = file->alias;
            goto try_alias;
         }
         ast_log(LOG_ERROR, "%s is missing! Cannot load %s\n", file->filename, info->module);
         res = ACO_PROCESS_ERROR;
         break;
      }

      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);
   return res;
}

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 578 of file config_options.c.

References aco_option_find(), ao2_cleanup, ao2_ref, ast_log(), ast_strlen_zero(), ast_variable::file, ast_variable::lineno, LOG_ERROR, LOG_WARNING, ast_variable::name, and ast_variable::value.

Referenced by aco_process_category_options().

{
   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;
   }
   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;
}

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

Set all default options of obj.

Parameters:

info	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 704 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, aco_type_internal::opts, and var.

Referenced by __ast_udptl_reload(), aco_process_config(), and process_category().

{
   struct aco_option *opt;
   struct ao2_iterator iter;

   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;
}

Asterisk developer's documentation

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation