config_options.h File Reference

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:

Go to the source code of 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, 0, 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, 0);
 Register a config option.
#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.
#define ACO_TYPES(...)   { __VA_ARGS__, NULL, }
 A helper macro to ensure that aco_info types always have a sentinel.
#define ARGIFY(...)   __VA_ARGS__
 Take a comma-separated list and allow it to be passed as a single argument to another macro.
#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.
#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.
#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.
#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.
#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.
#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.
#define PASTE1(arg1, arg2)   arg1##arg2
#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.
#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.
#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.
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, unsigned int no_doc, 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_containeraco_option_container_alloc (void)
 Allocate a container to hold config options.
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.
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.
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 170 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, 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 564 of file config_options.h.

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

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

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

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

Referenced by load_config().

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

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

Definition at line 169 of file config_options.h.

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

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

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

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

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

Definition at line 705 of file config_options.h.

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

Definition at line 707 of file config_options.h.

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

Definition at line 709 of file config_options.h.

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

Definition at line 711 of file config_options.h.

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

Definition at line 713 of file config_options.h.

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

Definition at line 715 of file config_options.h.

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

Definition at line 717 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 776 of file config_options.h.

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

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

Definition at line 209 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
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 201 of file config_options.h.

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

Definition at line 217 of file config_options.h.

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

Referenced by alloc_and_initialize_sorcery(), apply_list_configuration(), ast_ari_config_init(), ast_bucket_init(), ast_cel_engine_init(), ast_named_acl_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_qualify(), ast_sip_initialize_sorcery_transport(), ast_sip_initialize_system(), AST_TEST_DEFINE(), ast_udptl_init(), conf_load_config(), load_config(), load_module(), mwi_sorcery_init(), process_config(), and stasis_init().

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

Definition at line 758 of file config_options.h.

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

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

Definition at line 692 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.
Parameters:
... varags A list of arguments
 * POPPED(a, b, c) -> b, c
 * 

Definition at line 789 of file config_options.h.

#define POPPED1 ( x,
...   )     __VA_ARGS__

Definition at line 790 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 768 of file config_options.h.

Referenced by ast_ari_config_init(), ast_bucket_init(), ast_cel_engine_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(), and load_module().

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

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

Definition at line 739 of file config_options.h.


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 458 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 140 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 133 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 146 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

Whether a category regex is a blackist or a whitelist.

Enumerator:
ACO_BLACKLIST 
ACO_WHITELIST 

Definition at line 46 of file config_options.h.

00046                      {
00047    ACO_BLACKLIST = 0,
00048    ACO_WHITELIST,
00049 };

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.

00052                    {
00053    ACO_EXACT = 1,
00054    ACO_REGEX,
00055 };

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}

Definition at line 247 of file config_options.h.

00247                      {
00248    /*! \brief Type for default option handler for ACLs
00249     * \note aco_option_register flags:
00250     *   non-zero : "permit"
00251     *   0        : "deny"
00252     * aco_option_register varargs:
00253     *   FLDSET macro with the field of type struct ast_ha *.
00254     *
00255     * Example:
00256     * {code}
00257     * struct test_item {
00258     *     struct ast_ha *ha;
00259     * };
00260     * aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
00261     * aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
00262     * {code}
00263     */
00264    OPT_ACL_T,
00265 
00266    /*! \brief Type for default option handler for bools (ast_true/ast_false)
00267     * \note aco_option_register flags:
00268     *   non-zero : process via ast_true
00269     *   0        : process via ast_false
00270     * aco_option_register varargs:
00271     *   FLDSET macro with the field of type int. It is important to note that the field
00272     *   cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
00273     *
00274     * Example:
00275     * {code}
00276     * struct test_item {
00277     *     int enabled;
00278     * };
00279     * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
00280     * {endcode}
00281     */
00282    OPT_BOOL_T,
00283 
00284    /*! \brief Type for default option handler for bools (ast_true/ast_false) that are stored in a flag
00285     * \note aco_option_register flags:
00286     *   non-zero : process via ast_true
00287     *   0        : process via ast_false
00288     * aco_option_register varargs:
00289     *   FLDSET macro with the field of type of unsigned int.
00290     *   The flag to set
00291     *
00292     * Example:
00293     * {code}
00294     * #define MY_TYPE_ISQUIET    1 << 4
00295     * struct test_item {
00296     *     unsigned int flags;
00297     * };
00298     * aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET);
00299     * {endcode}
00300     */
00301    OPT_BOOLFLAG_T,
00302 
00303    /*! \brief Type for default option handler for character array strings
00304     * \note aco_option_register flags:
00305     *   non-zero : String cannot be empty.
00306     *   0        : String can be empty.
00307     * \note aco_option_register varargs:
00308     *   CHARFLDSET macro with a field of type char[]
00309     *
00310     * Example:
00311     * {code}
00312     * struct test_item {
00313     *     char description[128];
00314     * };
00315     * aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description));
00316     * {endcode}
00317     */
00318    OPT_CHAR_ARRAY_T,
00319 
00320    /*! \brief Type for default option handler for format capabilities
00321     * \note aco_option_register flags:
00322     *   non-zero : This is an "allow" style option
00323     *   0        : This is a "disallow" style option
00324     * aco_option_register varargs:
00325     *   FLDSET macro with field representing a struct ast_format_cap *
00326     *
00327     * Example:
00328     * {code}
00329     * struct test_item {
00330     *     struct ast_format cap *cap;
00331     * };
00332     * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
00333     * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
00334     * {endcode}
00335     */
00336    OPT_CODEC_T,
00337 
00338    /*! \brief Type for a custom (user-defined) option handler */
00339    OPT_CUSTOM_T,
00340 
00341    /*! \brief Type for default option handler for doubles
00342     *
00343     * \note aco_option_register flags:
00344     *   See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function
00345     * aco_option_register varargs:
00346     *   FLDSET macro with the field of type double
00347     *
00348     * Example:
00349     * struct test_item {
00350     *     double dub;
00351     * };
00352     * {code}
00353     * aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
00354     * {endcode}
00355     */
00356    OPT_DOUBLE_T,
00357 
00358    /*! \brief Type for default option handler for signed integers
00359     *
00360     * \note aco_option_register flags:
00361     *   See flags available for use with the PARSE_INT32 type for the ast_parse_arg function
00362     * aco_option_register varargs:
00363     *   FLDSET macro with the field of type int32_t
00364     *   The remaining varargs for should be arguments compatible with the varargs for the
00365     *   ast_parse_arg function with the PARSE_INT32 type and the flags passed in the
00366     *   aco_option_register flags parameter.
00367     *
00368     * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
00369     * contains an invalid value, it is better to let the config loading fail with warnings so that
00370     * the problem is fixed by the administrator.
00371     *
00372     * Example:
00373     * struct test_item {
00374     *     int32_t intopt;
00375     * };
00376     * {code}
00377     * aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
00378     * {endcode}
00379     */
00380    OPT_INT_T,
00381 
00382    /*! \brief Type for a default handler that should do nothing
00383     *
00384     * \note This might be useful for a "type" field that is valid, but doesn't
00385     * actually need to do anything
00386     */
00387    OPT_NOOP_T,
00388 
00389    /*! \brief Type for default handler for ast_sockaddrs
00390     *
00391     * \note aco_option_register flags:
00392     *   See flags available for use with the PARSE_ADDR type for the ast_parse_arg function
00393     * aco_option_register varargs:
00394     *   FLDSET macro with the field being of type struct ast_sockaddr.
00395     *
00396     * Example:
00397     * {code}
00398     * struct test_item {
00399     *     struct ast_sockaddr addr;
00400     * };
00401     * aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
00402     * {endcode}
00403     */
00404    OPT_SOCKADDR_T,
00405 
00406    /*! \brief Type for default option handler for stringfields
00407     * \note aco_option_register flags:
00408     *   non-zero : String cannot be empty.
00409     *   0        : String can be empty.
00410     * aco_option_register varargs:
00411     *   STRFLDSET macro with the field being the field created by AST_STRING_FIELD
00412     *
00413     * Example:
00414     * {code}
00415     * struct test_item {
00416     *     AST_DECLARE_STRING_FIELDS(
00417     *         AST_STRING_FIELD(thing);
00418     *     );
00419     * };
00420     * aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing));
00421     * {endcode}
00422     */
00423    OPT_STRINGFIELD_T,
00424 
00425    /*! \brief Type for default option handler for unsigned integers
00426     *
00427     * \note aco_option_register flags:
00428     *   See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function
00429     * aco_option_register varargs:
00430     *   FLDSET macro with the field of type uint32_t
00431     *   The remaining varargs for should be arguments compatible with the varargs for the
00432     *   ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the
00433     *   aco_option_register flags parameter.
00434     *
00435     * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
00436     * contains an invalid value, it is better to let the config loading fail with warnings so that
00437     * the problem is fixed by the administrator.
00438     *
00439     * Example:
00440     * struct test_item {
00441     *     int32_t intopt;
00442     * };
00443     * {code}
00444     * aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
00445     * {endcode}
00446     */
00447    OPT_UINT_T,
00448 };

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

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

enum aco_type_t

Enumerator:
ACO_GLOBAL 
ACO_ITEM 

Definition at line 40 of file config_options.h.

00040                 {
00041    ACO_GLOBAL,
00042    ACO_ITEM,
00043 };


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,
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 287 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, aco_option::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().

00290 {
00291    struct aco_option *opt;
00292    va_list ap;
00293    int tmp;
00294 
00295    /* Custom option types require a handler */
00296    if (!handler && kind == OPT_CUSTOM_T) {
00297       return -1;
00298    }
00299 
00300    if (!(types && types[0])) {
00301       return -1;
00302    }
00303 
00304    if (!(opt = ao2_alloc(sizeof(*opt) + argc * sizeof(opt->args[0]), config_option_destroy))) {
00305       return -1;
00306    }
00307 
00308    if (matchtype == ACO_REGEX && !(opt->name_regex = build_regex(name))) {
00309       ao2_ref(opt, -1);
00310       return -1;
00311    }
00312 
00313    va_start(ap, argc);
00314    for (tmp = 0; tmp < argc; tmp++) {
00315       opt->args[tmp] = va_arg(ap, size_t);
00316    }
00317    va_end(ap);
00318 
00319    opt->name = name;
00320    opt->match_type = matchtype;
00321    opt->default_val = default_val;
00322    opt->type = kind;
00323    opt->handler = handler;
00324    opt->flags = flags;
00325    opt->argc = argc;
00326    opt->no_doc = no_doc;
00327 
00328    if (!opt->handler && !(opt->handler = ast_config_option_default_handler(opt->type))) {
00329       /* This should never happen */
00330       ast_log(LOG_ERROR, "No handler provided, and no default handler exists for type %u\n", opt->type);
00331       ao2_ref(opt, -1);
00332       return -1;
00333    };
00334 
00335    if (link_option_to_types(info, types, opt)) {
00336       ao2_ref(opt, -1);
00337       return -1;
00338    }
00339 
00340    return 0;
00341 }

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 821 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_features_config_shutdown(), cdr_engine_shutdown(), cel_engine_cleanup(), conf_destroy_config(), destroy_config(), load_module(), named_acl_cleanup(), sorcery_object_type_destructor(), stasis_cleanup(), udptl_shutdown(), and unload_module().

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

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

References aco_info_destroy(), ACO_WHITELIST, ast_calloc, aco_type::category, aco_type::category_match, error(), 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, and aco_file::types.

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

00790 {
00791    size_t x = 0, y = 0;
00792    struct aco_file *file;
00793    struct aco_type *type;
00794 
00795    if (!(info->internal = ast_calloc(1, sizeof(*info->internal)))) {
00796       return -1;
00797    }
00798 
00799    while ((file = info->files[x++])) {
00800       while ((type = file->types[y++])) {
00801          if (internal_type_init(type)) {
00802             goto error;
00803          }
00804 #ifdef AST_XML_DOCS
00805          if (!info->hidden &&
00806             !type->hidden &&
00807             xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match == ACO_WHITELIST)) {
00808             goto error;
00809          }
00810 #endif /* AST_XML_DOCS */
00811       }
00812       y = 0;
00813    }
00814 
00815    return 0;
00816 error:
00817    aco_info_destroy(info);
00818    return -1;
00819 }

struct ao2_container* aco_option_container_alloc ( void   )  [read]

Allocate a container to hold config options.

Definition at line 389 of file config_options.c.

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

Referenced by internal_type_init().

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

References aco_option::args.

Referenced by timeval_str2struct().

00236 {
00237    return option->args[position];
00238 }

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

References aco_option::flags.

Referenced by option_handler_parkedfeature().

00231 {
00232    return option->flags;
00233 }

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 205 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, and aco_option::name.

Referenced by AST_TEST_DEFINE().

00206 {
00207    struct aco_option *opt;
00208 
00209    if (!info || ast_strlen_zero(name) || ast_strlen_zero(aliased_to)) {
00210       return -1;
00211    }
00212 
00213    if (!(opt = ao2_alloc(sizeof(*opt), config_option_destroy))) {
00214       return -1;
00215    }
00216 
00217    opt->name = name;
00218    opt->aliased_to = aliased_to;
00219    opt->deprecated = 1;
00220    opt->match_type = ACO_EXACT;
00221 
00222    if (link_option_to_types(info, types, opt)) {
00223       ao2_ref(opt, -1);
00224       return -1;
00225    }
00226 
00227    return 0;
00228 }

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 99 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(), menu_template_handler(), udptl_pre_apply_config(), unbound_config_preapply_callback(), verify_default_parking_lot(), and verify_default_profiles().

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

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 556 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, aco_info_internal::pending, aco_info::pre_apply_config, and aco_info::snapshot_alloc.

00557 {
00558    if (!info->internal) {
00559       ast_log(LOG_ERROR, "Attempt to process %s with uninitialized aco_info\n", file->filename);
00560       goto error;
00561    }
00562 
00563    if (!(info->internal->pending = info->snapshot_alloc())) {
00564       ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", file->filename);
00565       goto error;
00566    }
00567 
00568    if (internal_process_ast_config(info, file, cfg)) {
00569       goto error;
00570    }
00571 
00572    if (info->pre_apply_config && info->pre_apply_config()) {
00573       goto error;
00574    }
00575 
00576    if (apply_config(info)) {
00577       goto error;
00578    };
00579 
00580    ao2_cleanup(info->internal->pending);
00581    return ACO_PROCESS_OK;
00582 
00583 error:
00584    ao2_cleanup(info->internal->pending);
00585    return ACO_PROCESS_ERROR;
00586 }

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

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

Referenced by process_category().

00728 {
00729    struct ast_variable *var;
00730 
00731    for (var = ast_variable_browse(cfg, cat); var; var = var->next) {
00732       if (aco_process_var(type, cat, var, obj)) {
00733          return -1;
00734       }
00735    }
00736 
00737    return 0;
00738 }

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 588 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_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, 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_cel_engine_init(), ast_cel_engine_reload(), ast_features_config_reload(), ast_named_acl_init(), ast_named_acl_reload(), AST_TEST_DEFINE(), conf_load_config(), conf_reload_config(), load_config(), load_module(), process_config(), reload(), reload_module(), and stasis_init().

00589 {
00590    struct ast_config *cfg;
00591    struct ast_flags cfg_flags = { reload ? CONFIG_FLAG_FILEUNCHANGED : 0, };
00592    int res = ACO_PROCESS_OK;
00593    int file_count = 0;
00594    struct aco_file *file;
00595 
00596    if (!info->internal) {
00597       ast_log(LOG_ERROR, "Attempting to process uninitialized aco_info\n");
00598       return ACO_PROCESS_ERROR;
00599    }
00600 
00601    if (!(info->files[0])) {
00602       ast_log(LOG_ERROR, "No filename given, cannot proceed!\n");
00603       return ACO_PROCESS_ERROR;
00604    }
00605 
00606    if (!(info->internal->pending = info->snapshot_alloc())) {
00607       ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", info->module);
00608       return ACO_PROCESS_ERROR;
00609    }
00610 
00611    while (res != ACO_PROCESS_ERROR && (file = info->files[file_count++])) {
00612       const char *filename = file->filename;
00613       struct aco_type *match;
00614       int i;
00615 
00616       /* set defaults for global objects */
00617       for (i = 0, match = file->types[i]; match; match = file->types[++i]) {
00618          void **field = info->internal->pending + match->item_offset;
00619 
00620          if (match->type != ACO_GLOBAL || !*field) {
00621             continue;
00622          }
00623 
00624          if (aco_set_defaults(match, match->category, *field)) {
00625             ast_log(LOG_ERROR, "In %s: Setting defaults for %s failed\n", file->filename, match->category);
00626             res = ACO_PROCESS_ERROR;
00627             break;
00628          }
00629       }
00630 
00631       if (res == ACO_PROCESS_ERROR) {
00632          break;
00633       }
00634 
00635 try_alias:
00636       cfg = ast_config_load(filename, cfg_flags);
00637       if (!cfg || cfg == CONFIG_STATUS_FILEMISSING) {
00638          if (file->alias && strcmp(file->alias, filename)) {
00639             filename = file->alias;
00640             goto try_alias;
00641          }
00642          ast_log(LOG_ERROR, "Unable to load config file '%s'\n", file->filename);
00643          res = ACO_PROCESS_ERROR;
00644          break;
00645       } else if (cfg == CONFIG_STATUS_FILEUNCHANGED) {
00646          ast_debug(1, "%s was unchanged\n", file->filename);
00647          res = ACO_PROCESS_UNCHANGED;
00648          continue;
00649       } else if (cfg == CONFIG_STATUS_FILEINVALID) {
00650          ast_log(LOG_ERROR, "Contents of %s are invalid and cannot be parsed\n",
00651             file->filename);
00652          res = ACO_PROCESS_ERROR;
00653          break;
00654       }
00655 
00656       /* A file got loaded. */
00657       if (reload) {
00658          /* Must do any subsequent file loads unconditionally. */
00659          reload = 0;
00660          ast_clear_flag(&cfg_flags, CONFIG_FLAG_FILEUNCHANGED);
00661 
00662          if (file_count != 1) {
00663             /*
00664              * Must restart loading to load all config files since a file
00665              * after the first one changed.
00666              */
00667             file_count = 0;
00668          } else {
00669             res = internal_process_ast_config(info, file, cfg);
00670          }
00671       } else {
00672          res = internal_process_ast_config(info, file, cfg);
00673       }
00674       ast_config_destroy(cfg);
00675    }
00676 
00677    if (res != ACO_PROCESS_OK) {
00678       goto end;
00679    }
00680 
00681    if (info->pre_apply_config && info->pre_apply_config()) {
00682       res = ACO_PROCESS_ERROR;
00683       goto end;
00684    }
00685 
00686    if (apply_config(info)) {
00687       res = ACO_PROCESS_ERROR;
00688       goto end;
00689    }
00690 
00691    if (info->post_apply_config) {
00692       info->post_apply_config();
00693    }
00694 
00695 end:
00696    ao2_cleanup(info->internal->pending);
00697    return res;
00698 }

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

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

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

00700 {
00701    RAII_VAR(struct aco_option *, opt, aco_option_find(type, var->name), ao2_cleanup);
00702    if (opt && opt->deprecated && !ast_strlen_zero(opt->aliased_to)) {
00703       const char *alias = ast_strdupa(opt->aliased_to);
00704       ast_log(LOG_WARNING, "At line %d of %s option '%s' is deprecated. Use '%s' instead\n", var->lineno, var->file, var->name, alias);
00705       ao2_ref(opt, -1);
00706       opt = aco_option_find(type, alias);
00707    }
00708 
00709    if (!opt) {
00710       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);
00711       return -1;
00712    }
00713 
00714    if (!opt->handler) {
00715       /* It should be impossible for an option to not have a handler */
00716       ast_log(LOG_ERROR, "BUG! Somehow a config option for %s/%s was created with no handler!\n", cat, var->name);
00717       return -1;
00718    }
00719    if (opt->handler(opt, var, obj)) {
00720       ast_log(LOG_ERROR, "Error parsing %s=%s at line %d of %s\n", var->name, var->value, var->lineno, var->file);
00721       return -1;
00722    }
00723 
00724    return 0;
00725 }

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 835 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, NULL, aco_type_internal::opts, RAII_VAR, and var.

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

00836 {
00837    struct aco_option *opt;
00838    struct ao2_iterator iter;
00839 
00840    iter = ao2_iterator_init(type->internal->opts, 0);
00841 
00842    while ((opt = ao2_iterator_next(&iter))) {
00843       RAII_VAR(struct ast_variable *, var, NULL, ast_variables_destroy);
00844 
00845       if (ast_strlen_zero(opt->default_val)) {
00846          ao2_ref(opt, -1);
00847          continue;
00848       }
00849       if (!(var = ast_variable_new(opt->name, opt->default_val, ""))) {
00850          ao2_ref(opt, -1);
00851          ao2_iterator_destroy(&iter);
00852          return -1;
00853       }
00854       if (opt->handler(opt, var, obj)) {
00855          ast_log(LOG_ERROR, "Unable to set default for %s, %s=%s\n", category, var->name, var->value);
00856          ao2_ref(opt, -1);
00857          ao2_iterator_destroy(&iter);
00858          return -1;
00859       }
00860       ao2_ref(opt, -1);
00861    }
00862    ao2_iterator_destroy(&iter);
00863 
00864    return 0;
00865 }


Generated on Thu Apr 16 06:30:27 2015 for Asterisk - The Open Source Telephony Project by  doxygen 1.5.6