Asterisk - The Open Source Telephony Project GIT-master-3dae2cf
Data Structures | Macros | Typedefs | Enumerations | Functions
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...
 

Macros

#define ACO_FILES(...)   { __VA_ARGS__, NULL, }
 
#define aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...)    __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 Register a config option. More...
 
#define aco_option_register_custom(info, name, matchtype, types, default_val, handler, flags)    __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
 Register a config option. More...
 
#define aco_option_register_custom_nodoc(info, name, matchtype, types, default_val, handler, flags)    __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);
 Register a config option with no expected documentation. More...
 
#define ACO_TYPES(...)   { __VA_ARGS__, NULL, }
 A helper macro to ensure that aco_info types always have a sentinel. More...
 
#define ARGIFY(...)   __VA_ARGS__
 Take a comma-separated list and allow it to be passed as a single argument to another macro. More...
 
#define ARGMAP(func, func_arg, x, ...)   ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
 Map func(func_arg, field) across all fields including x. More...
 
#define ARGMAP_(N, func, func_arg, x, ...)   PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)
 
#define ARGMAP_1(func, func_arg, in, x, ...)   ARGIFY(in, func(func_arg, x))
 The individual field handlers for ARGMAP. More...
 
#define ARGMAP_2(func, func_arg, in, x, ...)    ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_3(func, func_arg, in, x, ...)    ARGMAP_2(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_4(func, func_arg, in, x, ...)    ARGMAP_3(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_5(func, func_arg, in, x, ...)    ARGMAP_4(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_6(func, func_arg, in, x, ...)    ARGMAP_5(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_7(func, func_arg, in, x, ...)    ARGMAP_6(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define ARGMAP_8(func, func_arg, in, x, ...)    ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
 
#define CHARFLDSET(type, field)   ARGIFY(offsetof(type, field), sizeof(((type *)0)->field))
 A helper macro to pass the appropriate arguments to aco_option_register for OPT_CHAR_ARRAY_T. More...
 
#define CONFIG_INFO_CORE(mod, name, arr, alloc, ...)
 
#define CONFIG_INFO_STANDARD(name, arr, alloc, ...)
 Declare an aco_info struct with default module and preload values. More...
 
#define CONFIG_INFO_TEST(name, arr, alloc, ...)
 
#define FLDSET(type, ...)   FLDSET1(type, ##__VA_ARGS__)
 Convert a struct and list of fields to an argument list of field offsets. More...
 
#define FLDSET1(type, ...)   POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))
 
#define PASTE(arg1, arg2)   PASTE1(arg1, arg2)
 Paste two arguments together, even if they are macros themselves. More...
 
#define PASTE1(arg1, arg2)   arg1##arg2
 
#define POPPED(...)   POPPED1(__VA_ARGS__)
 A list of arguments without the first argument. More...
 
#define POPPED1(x, ...)   __VA_ARGS__
 
#define STRFLDSET(type, ...)   FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
 Convert a struct and a list of stringfield fields to an argument list of field offsets. More...
 
#define VA_NARGS(...)   VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
 Results in the number of arguments passed to it. More...
 
#define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...)   N
 

Typedefs

typedef int(* aco_matchvalue_func) (const char *text)
 A function for determining whether the value for the matchfield in an aco_type is sufficient for a match. More...
 
typedef int(* aco_option_handler) (const struct aco_option *opt, struct ast_variable *var, void *obj)
 A callback function for handling a particular option. More...
 
typedef void(* aco_post_apply_config) (void)
 A callback function called only if config changes have been applied. More...
 
typedef int(* aco_pre_apply_config) (void)
 A callback function to run just prior to applying config changes. More...
 
typedef void *(* aco_snapshot_alloc) (void)
 A callback function for allocating an object to hold all config objects. More...
 
typedef void *(* aco_type_item_alloc) (const char *category)
 Allocate a configurable ao2 object. More...
 
typedef void *(* aco_type_item_find) (struct ao2_container *newcontainer, const char *category)
 Find a item given a category and container of items. More...
 
typedef int(* aco_type_item_pre_process) (void *newitem)
 Callback function that is called after a config object is initialized with defaults. More...
 
typedef int(* aco_type_prelink) (void *newitem)
 Callback function that is called after config processing, but before linking. More...
 

Enumerations

enum  aco_category_op {
  ACO_BLACKLIST = 0 , ACO_WHITELIST , ACO_BLACKLIST_EXACT , ACO_WHITELIST_EXACT ,
  ACO_BLACKLIST_ARRAY , ACO_WHITELIST_ARRAY
}
 
enum  aco_matchtype { ACO_EXACT = 1 , ACO_REGEX , ACO_PREFIX }
 What kind of matching should be done on an option name. More...
 
enum  aco_option_type {
  OPT_ACL_T , OPT_BOOL_T , OPT_BOOLFLAG_T , OPT_CHAR_ARRAY_T ,
  OPT_CODEC_T , OPT_CUSTOM_T , OPT_DOUBLE_T , OPT_INT_T ,
  OPT_NOOP_T , OPT_SOCKADDR_T , OPT_STRINGFIELD_T , OPT_UINT_T ,
  OPT_YESNO_T , OPT_TIMELEN_T
}
 The option types. More...
 
enum  aco_process_status { ACO_PROCESS_OK , ACO_PROCESS_UNCHANGED , ACO_PROCESS_ERROR }
 Return values for the aco_process functions. More...
 
enum  aco_type_t { ACO_GLOBAL , ACO_ITEM , ACO_IGNORE }
 

Functions

int __aco_option_register (struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types, const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc,...)
 register a config option More...
 
void aco_info_destroy (struct aco_info *info)
 Destroy an initialized aco_info struct. More...
 
int aco_info_init (struct aco_info *info)
 Initialize an aco_info structure. More...
 
struct ao2_containeraco_option_container_alloc (void)
 Allocate a container to hold config options. More...
 
intptr_t aco_option_get_argument (const struct aco_option *option, unsigned int position)
 Get the offset position for an argument within a config option. More...
 
unsigned int aco_option_get_flags (const struct aco_option *option)
 Read the flags of a config option - useful when using a custom callback for a config option. More...
 
int aco_option_register_deprecated (struct aco_info *info, const char *name, struct aco_type **types, const char *aliased_to)
 Register a deprecated (and aliased) config option. More...
 
void * aco_pending_config (struct aco_info *info)
 Get pending config changes. More...
 
enum aco_process_status aco_process_ast_config (struct aco_info *info, struct aco_file *file, struct ast_config *cfg)
 Process config info from an ast_config via options registered with an aco_info. More...
 
int aco_process_category_options (struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj)
 Parse each option defined in a config category. More...
 
enum aco_process_status aco_process_config (struct aco_info *info, int reload)
 Process a config info via the options registered with an aco_info. More...
 
int aco_process_var (struct aco_type *type, const char *cat, struct ast_variable *var, void *obj)
 Parse a single ast_variable and apply it to an object. More...
 
int aco_set_defaults (struct aco_type *type, const char *category, void *obj)
 Set all default options of obj. More...
 

Detailed Description

Configuration option-handling.

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

Definition in file config_options.h.

Macro Definition Documentation

◆ ACO_FILES

#define ACO_FILES (   ...)    { __VA_ARGS__, NULL, }
Examples
app_skel.c.

Definition at line 182 of file config_options.h.

◆ aco_option_register

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

Register a config option.

Parameters
infoA pointer to the aco_info struct
nameThe name of the option
matchtype
typesAn array of valid option types for matching categories to the correct struct type
default_valThe default value of the option in the same format as defined in a config file
opt_typeThe option type for default option type handling
flagsa type specific flags, stored in the option and available to the handler
...
Return values
0Success
-1Failure
Examples
app_skel.c.

Definition at line 623 of file config_options.h.

◆ aco_option_register_custom

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

Register a config option.

Parameters
infoA pointer to the aco_info struct
nameThe name of the option
matchtype
typesAn array of valid option types for matching categories to the correct struct type
default_valThe default value of the option in the same format as defined in a config file
handlerThe handler callback for the option
flagstype specific flags, stored in the option and available to the handler
Return values
0Success
-1Failure
Examples
app_skel.c.

Definition at line 638 of file config_options.h.

◆ aco_option_register_custom_nodoc

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

Register a config option with no expected documentation.

Parameters
infoA pointer to the aco_info struct
nameThe name of the option
matchtype
typesAn array of valid option types for matching categories to the correct struct type
default_valThe default value of the option in the same format as defined in a config file
handlerThe handler callback for the option
flagstype 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
0Success
-1Failure

Definition at line 656 of file config_options.h.

◆ ACO_TYPES

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

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

Examples
app_skel.c.

Definition at line 181 of file config_options.h.

◆ ARGIFY

#define ARGIFY (   ...)    __VA_ARGS__

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

Definition at line 754 of file config_options.h.

◆ ARGMAP

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

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

Note
Everything below this point is to handle converting varargs containing field names, to varargs containing a count of args, followed by the offset of each of the field names in the struct type that is passed in. It is currently limited to 8 arguments, but 8 variadic arguments, like 640K, should be good enough for anyone. If not, it is easy to add more.
Parameters
funcThe function (almost certainly offsetof) to map across the fields
func_argThe first argument (almost certainly a type (e.g. "struct mystruct")
xThe first field
...varargs The rest of the fields

Example usage:

struct foo {
int a;
char *b;
foo *c;
};
ARGMAP(offsetof, struct foo, a, c)
#define ARGMAP(func, func_arg, x,...)
Map func(func_arg, field) across all fields including x.
static struct test_val b
static struct test_val a
static struct test_val c

produces the string:

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

which can be passed as the varargs to some other function

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

As an example of how the processing works:

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

Definition at line 738 of file config_options.h.

◆ ARGMAP_

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

Definition at line 744 of file config_options.h.

◆ ARGMAP_1

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

The individual field handlers for ARGMAP.

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

Definition at line 763 of file config_options.h.

◆ ARGMAP_2

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

Definition at line 764 of file config_options.h.

◆ ARGMAP_3

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

Definition at line 766 of file config_options.h.

◆ ARGMAP_4

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

Definition at line 768 of file config_options.h.

◆ ARGMAP_5

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

Definition at line 770 of file config_options.h.

◆ ARGMAP_6

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

Definition at line 772 of file config_options.h.

◆ ARGMAP_7

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

Definition at line 774 of file config_options.h.

◆ ARGMAP_8

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

Definition at line 776 of file config_options.h.

◆ CHARFLDSET

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

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

Note
This will pass the offset of the field and its length as arguments
Parameters
typeThe type with the char array field (e.g. "struct my_struct")
fieldThe name of char array field

Definition at line 835 of file config_options.h.

◆ CONFIG_INFO_CORE

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

Definition at line 221 of file config_options.h.

◆ CONFIG_INFO_STANDARD

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

Declare an aco_info struct with default module and preload values.

Parameters
nameThe name of the struct
arrThe global object array for holding the user-defined config object
allocThe allocater for the user-defined config object

Example:

.pre_apply_config = skel_pre_apply_config,
.files = { &app_skel_conf, NULL },
);
...
if (aco_info_init(&cfg_info)) {
}
...
aco_info_destroy(&cfg_info);
static void * skel_config_alloc(void)
Allocate a skel_config to hold a snapshot of the complete results of parsing a config.
Definition: app_skel.c:567
struct aco_file app_skel_conf
Definition: app_skel.c:281
#define AO2_GLOBAL_OBJ_STATIC(name)
Define a global object holder to be used to hold an ao2 object, statically initialized.
Definition: astobj2.h:847
static struct console_pvt globals
int aco_info_init(struct aco_info *info)
Initialize an aco_info structure.
#define CONFIG_INFO_STANDARD(name, arr, alloc,...)
Declare an aco_info struct with default module and preload values.
@ AST_MODULE_LOAD_DECLINE
Module has failed to load, may be in an inconsistent state.
Definition: module.h:78
#define NULL
Definition: resample.c:96

Definition at line 213 of file config_options.h.

◆ CONFIG_INFO_TEST

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

Definition at line 229 of file config_options.h.

◆ FLDSET

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

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

Parameters
typeThe 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)
#define FLDSET(type,...)
Convert a struct and list of fields to an argument list of field offsets.

produces

offsetof(struct foo, a), offsetof(struct foo, c)
Examples
app_skel.c.

Definition at line 816 of file config_options.h.

◆ FLDSET1

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

Definition at line 817 of file config_options.h.

◆ PASTE

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

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

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

Definition at line 750 of file config_options.h.

◆ PASTE1

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

Definition at line 751 of file config_options.h.

◆ POPPED

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

A list of arguments without the first argument.

Note
Used internally to remove the leading "number of arguments" argument from ARGMAP for FLDSET. This is because a call to FLDSET may be followed by additional arguments in aco_register_option, so the true number of arguments will possibly be different than what ARGMAP returns.
Parameters
...varags A list of arguments
* POPPED(a, b, c) -> b, c
* 

Definition at line 848 of file config_options.h.

◆ POPPED1

#define POPPED1 (   x,
  ... 
)    __VA_ARGS__

Definition at line 849 of file config_options.h.

◆ STRFLDSET

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

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

Note
Stringfields require the passing of the field manager pool, and field manager to the default stringfield option handler, so registering options that point to stringfields requires this macro to be called instead of the FLDSET macro.
Parameters
typeThe type with the fields (e.g. "struct my_struct")
...varargs The fields in the struct whose offsets are needed as arguments
Examples
app_skel.c.

Definition at line 827 of file config_options.h.

◆ VA_NARGS

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

Results in the number of arguments passed to it.

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

Definition at line 797 of file config_options.h.

◆ VA_NARGS1

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

Definition at line 798 of file config_options.h.

Typedef Documentation

◆ aco_matchvalue_func

typedef int(* aco_matchvalue_func) (const char *text)

A function for determining whether the value for the matchfield in an aco_type is sufficient for a match.

Parameters
textThe value of the option
Return values
-1The value is sufficient for a match
0The value is not sufficient for a match

Definition at line 116 of file config_options.h.

◆ aco_option_handler

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

A callback function for handling a particular option.

Parameters
optThe option being configured
varThe config variable to use to configure obj
objThe object to be configured
Return values
0Parsing and recording the config value succeeded
non-zeroFailure. Parsing should stop and no reload applied

Definition at line 517 of file config_options.h.

◆ aco_post_apply_config

typedef void(* aco_post_apply_config) (void)

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

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

Definition at line 152 of file config_options.h.

◆ aco_pre_apply_config

typedef int(* aco_pre_apply_config) (void)

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

Return values
0Success
non-zeroFailure. Changes not applied

Definition at line 145 of file config_options.h.

◆ aco_snapshot_alloc

typedef void *(* aco_snapshot_alloc) (void)

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

Return values
NULLerror
non-NULLa config object container

Definition at line 158 of file config_options.h.

◆ aco_type_item_alloc

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

Allocate a configurable ao2 object.

Callback functions for option parsing via aco_process_config()

Parameters
categoryThe config category the object is being generated for
Return values
NULLerror
non-NULLa new configurable ao2 object

Definition at line 76 of file config_options.h.

◆ aco_type_item_find

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

Find a item given a category and container of items.

Parameters
newcontainerThe container to search for the item
categoryThe category associated with the item
Return values
non-NULLitem from the container
NULLitem does not exist in container

Definition at line 84 of file config_options.h.

◆ aco_type_item_pre_process

typedef int(* aco_type_item_pre_process) (void *newitem)

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

Note
This callback is called during config processing after a new config is allocated and and defaults applied but before values from the config are read. This callback could be used to merge in settings inherited from the global settings if necessary, despite that being a bad thing to do!
Parameters
newitemThe newly allocated config object with defaults populated
Return values
0succes, continue processing
non-zerofailure, stop processing

Definition at line 97 of file config_options.h.

◆ aco_type_prelink

typedef int(* aco_type_prelink) (void *newitem)

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

Note
This callback is called after config processing, but before linking the object in the config container. This callback can be used to verify that all settings make sense together, that required options have been set, etc.
Parameters
newitemThe newly configured object
Return values
0success, continue processing
non-zerofailure, stop processing

Definition at line 109 of file config_options.h.

Enumeration Type Documentation

◆ aco_category_op

Type of category matching to perform

Enumerator
ACO_BLACKLIST 

Regex based blacklist.

ACO_WHITELIST 

Regex based whitelist.

ACO_BLACKLIST_EXACT 

Blacklist with a single string matched with strcasecmp.

ACO_WHITELIST_EXACT 

Whitelist with a single string matched with strcasecmp.

ACO_BLACKLIST_ARRAY 

Blacklist with a NULL terminated array of strings matched with strcasecmp.

ACO_WHITELIST_ARRAY 

Whitelist with a NULL terminated array of strings matched with strcasecmp.

Definition at line 47 of file config_options.h.

47 {
48 /*! Regex based blacklist. */
49 ACO_BLACKLIST = 0,
50 /*! Regex based whitelist. */
52 /*! Blacklist with a single string matched with strcasecmp. */
54 /*! Whitelist with a single string matched with strcasecmp. */
56 /*! Blacklist with a NULL terminated array of strings matched with strcasecmp. */
58 /*! Whitelist with a NULL terminated array of strings matched with strcasecmp. */
60};
@ ACO_WHITELIST_ARRAY
@ ACO_BLACKLIST
@ ACO_WHITELIST_EXACT
@ ACO_WHITELIST
@ ACO_BLACKLIST_ARRAY
@ ACO_BLACKLIST_EXACT

◆ aco_matchtype

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

Enumerator
ACO_EXACT 
ACO_REGEX 
ACO_PREFIX 

Definition at line 63 of file config_options.h.

63 {
64 ACO_EXACT = 1,
67};
@ ACO_PREFIX
@ ACO_EXACT
@ ACO_REGEX

◆ 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:

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

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

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

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

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

aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
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; };

aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
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:

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

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

aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
OPT_YESNO_T 

Type for default option handler for bools (ast_true/ast_false)

Note
aco_option_register flags: non-zero : process via ast_true 0 : process via ast_false aco_option_register varargs: FLDSET macro with the field of type int. It is important to note that the field cannot be a bitfield. If bitfields are required, they must be set via a custom handler.

This is exactly the same as OPT_BOOL_T. The only difference is that when translated to a string, OPT_BOOL_T becomes "true" or "false"; OPT_YESNO_T becomes "yes" or "no".

Example:

struct test_item {
int enabled;
};
aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled));
OPT_TIMELEN_T 

Type for default option handler for time length signed integers.

Note
aco_option_register flags: See flags available for use with the PARSE_TIMELEN type for the ast_parse_arg function aco_option_register varargs: FLDSET macro with the field of type int The remaining varargs for should be arguments compatible with the varargs for the ast_parse_arg function with the PARSE_TIMELEN type and the flags passed in the aco_option_register flags parameter.
In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config contains an invalid value, it is better to let the config loading fail with warnings so that the problem is fixed by the administrator.

Example: struct test_item { int timelen; };

aco_option_register(&cfg_info, "timelen", ACO_EXACT, my_types, "3", OPT_TIMELEN_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), TIMELEN_MILLISECONDS, -10, 10);

Definition at line 259 of file config_options.h.

259 {
260 /*! \brief Type for default option handler for ACLs
261 * \note aco_option_register flags:
262 * non-zero : "permit"
263 * 0 : "deny"
264 * aco_option_register varargs:
265 * FLDSET macro with the field of type struct ast_ha *.
266 *
267 * Example:
268 * \code
269 * struct test_item {
270 * struct ast_ha *ha;
271 * };
272 * aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
273 * aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
274 * \endcode
275 */
276 OPT_ACL_T,
277
278 /*! \brief Type for default option handler for bools (ast_true/ast_false)
279 * \note aco_option_register flags:
280 * non-zero : process via ast_true
281 * 0 : process via ast_false
282 * aco_option_register varargs:
283 * FLDSET macro with the field of type int. It is important to note that the field
284 * cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
285 *
286 * Example:
287 * \code
288 * struct test_item {
289 * int enabled;
290 * };
291 * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
292 * \endcode
293 */
295
296 /*! \brief Type for default option handler for bools (ast_true/ast_false) that are stored in a flag
297 * \note aco_option_register flags:
298 * non-zero : process via ast_true
299 * 0 : process via ast_false
300 * aco_option_register varargs:
301 * FLDSET macro with the field of type of unsigned int.
302 * The flag to set
303 *
304 * Example:
305 * \code
306 * #define MY_TYPE_ISQUIET 1 << 4
307 * struct test_item {
308 * unsigned int flags;
309 * };
310 * aco_option_register(&cfg_info, "quiet", ACO_EXACT, my_types, "no", OPT_BOOLFLAG_T, 1, FLDSET(struct test_item, flags), MY_TYPE_ISQUIET);
311 * \endcode
312 */
314
315 /*! \brief Type for default option handler for character array strings
316 * \note aco_option_register flags:
317 * non-zero : String cannot be empty.
318 * 0 : String can be empty.
319 * \note aco_option_register varargs:
320 * CHARFLDSET macro with a field of type char[]
321 *
322 * Example:
323 * \code
324 * struct test_item {
325 * char description[128];
326 * };
327 * aco_option_register(&cfg_info, "description", ACO_EXACT, my_types, "none", OPT_CHAR_ARRAY_T, 0, CHARFLDSET(struct test_item, description));
328 * \endcode
329 */
331
332 /*! \brief Type for default option handler for format capabilities
333 * \note aco_option_register flags:
334 * non-zero : This is an "allow" style option
335 * 0 : This is a "disallow" style option
336 * aco_option_register varargs:
337 * FLDSET macro with field representing a struct ast_format_cap *
338 *
339 * Example:
340 * \code
341 * struct test_item {
342 * struct ast_format cap *cap;
343 * };
344 * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
345 * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
346 * \endcode
347 */
349
350 /*! \brief Type for a custom (user-defined) option handler */
352
353 /*! \brief Type for default option handler for doubles
354 *
355 * \note aco_option_register flags:
356 * See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function
357 * aco_option_register varargs:
358 * FLDSET macro with the field of type double
359 *
360 * Example:
361 * struct test_item {
362 * double dub;
363 * };
364 * \code
365 * aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, 0, FLDSET(struct test_item, dub));
366 * \endcode
367 */
369
370 /*! \brief Type for default option handler for signed integers
371 *
372 * \note aco_option_register flags:
373 * See flags available for use with the PARSE_INT32 type for the ast_parse_arg function
374 * aco_option_register varargs:
375 * FLDSET macro with the field of type int32_t
376 * The remaining varargs for should be arguments compatible with the varargs for the
377 * ast_parse_arg function with the PARSE_INT32 type and the flags passed in the
378 * aco_option_register flags parameter.
379 *
380 * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
381 * contains an invalid value, it is better to let the config loading fail with warnings so that
382 * the problem is fixed by the administrator.
383 *
384 * Example:
385 * struct test_item {
386 * int32_t intopt;
387 * };
388 * \code
389 * aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
390 * \endcode
391 */
392 OPT_INT_T,
393
394 /*! \brief Type for a default handler that should do nothing
395 *
396 * \note This might be useful for a "type" field that is valid, but doesn't
397 * actually need to do anything
398 */
400
401 /*! \brief Type for default handler for ast_sockaddrs
402 *
403 * \note aco_option_register flags:
404 * See flags available for use with the PARSE_ADDR type for the ast_parse_arg function
405 * aco_option_register varargs:
406 * FLDSET macro with the field being of type struct ast_sockaddr.
407 *
408 * Example:
409 * \code
410 * struct test_item {
411 * struct ast_sockaddr addr;
412 * };
413 * aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
414 * \endcode
415 */
417
418 /*! \brief Type for default option handler for stringfields
419 * \note aco_option_register flags:
420 * non-zero : String cannot be empty.
421 * 0 : String can be empty.
422 * aco_option_register varargs:
423 * STRFLDSET macro with the field being the field created by AST_STRING_FIELD
424 *
425 * Example:
426 * \code
427 * struct test_item {
428 * AST_DECLARE_STRING_FIELDS(
429 * AST_STRING_FIELD(thing);
430 * );
431 * };
432 * aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, thing));
433 * \endcode
434 */
436
437 /*! \brief Type for default option handler for unsigned integers
438 *
439 * \note aco_option_register flags:
440 * See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function
441 * aco_option_register varargs:
442 * FLDSET macro with the field of type uint32_t
443 * The remaining varargs for should be arguments compatible with the varargs for the
444 * ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the
445 * aco_option_register flags parameter.
446 *
447 * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
448 * contains an invalid value, it is better to let the config loading fail with warnings so that
449 * the problem is fixed by the administrator.
450 *
451 * Example:
452 * struct test_item {
453 * int32_t intopt;
454 * };
455 * \code
456 * aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
457 * \endcode
458 */
460
461 /*! \brief Type for default option handler for bools (ast_true/ast_false)
462 * \note aco_option_register flags:
463 * non-zero : process via ast_true
464 * 0 : process via ast_false
465 * aco_option_register varargs:
466 * FLDSET macro with the field of type int. It is important to note that the field
467 * cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
468 *
469 * This is exactly the same as OPT_BOOL_T. The only difference is that when
470 * translated to a string, OPT_BOOL_T becomes "true" or "false"; OPT_YESNO_T becomes
471 * "yes" or "no".
472 *
473 * Example:
474 * \code
475 * struct test_item {
476 * int enabled;
477 * };
478 * aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_YESNO_T, 1, FLDSET(struct test_item, enabled));
479 * \endcode
480 */
482
483 /*! \brief Type for default option handler for time length signed integers
484 *
485 * \note aco_option_register flags:
486 * See flags available for use with the PARSE_TIMELEN type for the ast_parse_arg function
487 * aco_option_register varargs:
488 * FLDSET macro with the field of type int
489 * The remaining varargs for should be arguments compatible with the varargs for the
490 * ast_parse_arg function with the PARSE_TIMELEN type and the flags passed in the
491 * aco_option_register flags parameter.
492 *
493 * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
494 * contains an invalid value, it is better to let the config loading fail with warnings so that
495 * the problem is fixed by the administrator.
496 *
497 * Example:
498 * struct test_item {
499 * int timelen;
500 * };
501 * \code
502 * aco_option_register(&cfg_info, "timelen", ACO_EXACT, my_types, "3", OPT_TIMELEN_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), TIMELEN_MILLISECONDS, -10, 10);
503 * \endcode
504 */
506
507};
@ OPT_UINT_T
Type for default option handler for unsigned integers.
@ OPT_NOOP_T
Type for a default handler that should do nothing.
@ OPT_CODEC_T
Type for default option handler for format capabilities.
@ OPT_BOOL_T
Type for default option handler for bools (ast_true/ast_false)
@ OPT_BOOLFLAG_T
Type for default option handler for bools (ast_true/ast_false) that are stored in a flag.
@ OPT_CUSTOM_T
Type for a custom (user-defined) option handler.
@ OPT_CHAR_ARRAY_T
Type for default option handler for character array strings.
@ OPT_ACL_T
Type for default option handler for ACLs.
@ OPT_SOCKADDR_T
Type for default handler for ast_sockaddrs.
@ OPT_YESNO_T
Type for default option handler for bools (ast_true/ast_false)
@ OPT_INT_T
Type for default option handler for signed integers.
@ OPT_TIMELEN_T
Type for default option handler for time length signed integers.
@ OPT_DOUBLE_T
Type for default option handler for doubles.
@ OPT_STRINGFIELD_T
Type for default option handler for stringfields.

◆ aco_process_status

Return values for the aco_process functions.

Enumerator
ACO_PROCESS_OK 

The config was processed and applied.

ACO_PROCESS_UNCHANGED 

The config had not been edited and no changes applied.

ACO_PROCESS_ERROR 

Their was an error and no changes were applied.

Definition at line 524 of file config_options.h.

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

◆ aco_type_t

enum aco_type_t
Enumerator
ACO_GLOBAL 
ACO_ITEM 
ACO_IGNORE 

Definition at line 40 of file config_options.h.

40 {
44};
@ ACO_ITEM
@ ACO_GLOBAL
@ ACO_IGNORE

Function Documentation

◆ __aco_option_register()

int __aco_option_register ( struct aco_info info,
const char *  name,
enum aco_matchtype  match_type,
struct aco_type **  types,
const char *  default_val,
enum aco_option_type  type,
aco_option_handler  handler,
unsigned int  flags,
unsigned int  no_doc,
size_t  argc,
  ... 
)

register a config option

Note
this should probably only be called by one of the aco_option_register* macros
Parameters
infoThe aco_info holding this module's config information
nameThe name of the option
match_type
typesAn array of valid option types for matching categories to the correct struct type
default_valThe default value of the option in the same format as defined in a config file
typeThe option type (only for default handlers)
handlerThe handler function for the option (only for non-default types)
flagsa type specific flags, stored in the option and available to the handler
no_docif non-zero, this option should not have documentation
argcThe number for variadic arguments
...field offsets to store for default handlers
Return values
0success
-1failure

Definition at line 300 of file config_options.c.

303{
304 struct aco_option *opt;
305 va_list ap;
306 int tmp;
307
308 /* Custom option types require a handler */
309 if (!handler && kind == OPT_CUSTOM_T) {
310 return -1;
311 }
312
313 if (!(types && types[0])) {
314 return -1;
315 }
316
317 opt = ao2_alloc_options(sizeof(*opt) + argc * sizeof(opt->args[0]),
319 if (!opt) {
320 return -1;
321 }
322
323 if (matchtype == ACO_REGEX && !(opt->name_regex = build_regex(name))) {
324 ao2_ref(opt, -1);
325 return -1;
326 }
327
328 va_start(ap, argc);
329 for (tmp = 0; tmp < argc; tmp++) {
330 opt->args[tmp] = va_arg(ap, size_t);
331 }
332 va_end(ap);
333
334 opt->name = name;
335 opt->match_type = matchtype;
337 opt->type = kind;
338 opt->handler = handler;
339 opt->flags = flags;
340 opt->argc = argc;
341 opt->no_doc = no_doc;
342
343 if (!opt->handler && !(opt->handler = ast_config_option_default_handler(opt->type))) {
344 /* This should never happen */
345 ast_log(LOG_ERROR, "No handler provided, and no default handler exists for type %u\n", opt->type);
346 ao2_ref(opt, -1);
347 return -1;
348 };
349
350 if (link_option_to_types(info, types, opt)) {
351 ao2_ref(opt, -1);
352 return -1;
353 }
354
355 return 0;
356}
#define ast_log
Definition: astobj2.c:42
@ AO2_ALLOC_OPT_LOCK_NOLOCK
Definition: astobj2.h:367
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_alloc_options(data_size, destructor_fn, options)
Definition: astobj2.h:404
static int tmp()
Definition: bt_open.c:389
static void config_option_destroy(void *obj)
static int link_option_to_types(struct aco_info *info, struct aco_type **types, struct aco_option *opt)
static regex_t * build_regex(const char *text)
static aco_option_handler ast_config_option_default_handler(enum aco_option_type type)
static const char name[]
Definition: format_mp3.c:68
#define LOG_ERROR
def info(msg)
regex_t * name_regex
unsigned int no_doc
const char * name
const char * default_val
unsigned int flags
intptr_t args[0]
enum aco_matchtype match_type
aco_option_handler handler
enum aco_option_type type
static void handler(const char *name, int response_code, struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct ast_json *body, struct ast_ari_response *response)
Definition: test_ari.c:59

References ACO_REGEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, aco_option::argc, aco_option::args, ast_config_option_default_handler(), ast_log, build_regex(), config_option_destroy(), aco_option::default_val, aco_option::flags, aco_option::handler, handler(), sip_to_pjsip::info(), link_option_to_types(), LOG_ERROR, aco_option::match_type, name, 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().

◆ aco_info_destroy()

void aco_info_destroy ( struct aco_info info)

Destroy an initialized aco_info struct.

Parameters
infoThe address of the aco_info struct to destroy
Examples
app_skel.c.

Definition at line 910 of file config_options.c.

911{
912 int x;
913 /* It shouldn't be possible for internal->pending to be in use when this is called because
914 * of the locks in loader.c around reloads and unloads and the fact that internal->pending
915 * only exists while those locks are held */
916 ast_free(info->internal);
917 info->internal = NULL;
918
919 for (x = 0; info->files[x]; x++) {
921 }
922}
#define ast_free(a)
Definition: astmm.h:180
static void internal_file_types_destroy(struct aco_file *file)

References ast_free, sip_to_pjsip::info(), internal_file_types_destroy(), and NULL.

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

◆ aco_info_init()

int aco_info_init ( struct aco_info info)

Initialize an aco_info structure.

Note
aco_info_destroy must be called if this succeeds
Parameters
infoThe address of an aco_info struct to initialize
Return values
0Success
non-zeroFailure
Examples
app_skel.c.

Definition at line 877 of file config_options.c.

878{
879 size_t x = 0, y = 0;
880 struct aco_file *file;
881 struct aco_type *type;
882
883 if (!(info->internal = ast_calloc(1, sizeof(*info->internal)))) {
884 return -1;
885 }
886
887 while ((file = info->files[x++])) {
888 while ((type = file->types[y++])) {
890 goto error;
891 }
892#ifdef AST_XML_DOCS
893 if (!info->hidden &&
894 !type->hidden &&
895 type->type != ACO_IGNORE &&
896 xmldoc_update_config_type(info->module, type->name, type->category, type->matchfield, type->matchvalue, type->category_match)) {
897 goto error;
898 }
899#endif /* AST_XML_DOCS */
900 }
901 y = 0;
902 }
903
904 return 0;
905error:
907 return -1;
908}
#define ast_calloc(num, len)
A wrapper for calloc()
Definition: astmm.h:202
static const char type[]
Definition: chan_ooh323.c:109
void aco_info_destroy(struct aco_info *info)
Destroy an initialized aco_info struct.
static int internal_type_init(struct aco_type *type)
static int xmldoc_update_config_type(const char *module, const char *name, const char *category, const char *matchfield, const char *matchvalue, enum aco_category_op category_match)
The representation of a single configuration file to be processed.
Type information about a category-level configurable object.
int error(const char *format,...)
Definition: utils/frame.c:999

References ACO_IGNORE, aco_info_destroy(), ast_calloc, error(), make_ari_stubs::file, sip_to_pjsip::info(), internal_type_init(), type, and xmldoc_update_config_type().

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

◆ aco_option_container_alloc()

struct ao2_container * aco_option_container_alloc ( void  )

Allocate a container to hold config options.

Definition at line 406 of file config_options.c.

407{
410}
@ AO2_ALLOC_OPT_LOCK_MUTEX
Definition: astobj2.h:363
#define ao2_container_alloc_hash(ao2_options, container_options, n_buckets, hash_fn, sort_fn, cmp_fn)
Allocate and initialize a hash container with the desired number of buckets.
Definition: astobj2.h:1303
#define CONFIG_OPT_BUCKETS
static int config_opt_hash(const void *obj, const int flags)
static int config_opt_cmp(void *obj, void *arg, int flags)

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

Referenced by internal_type_init().

◆ aco_option_get_argument()

intptr_t aco_option_get_argument ( const struct aco_option option,
unsigned int  position 
)

Get the offset position for an argument within a config option.

Parameters
optionPointer to the aco_option struct
positionArgument number
Return values
positionof the argument

Definition at line 248 of file config_options.c.

249{
250 return option->args[position];
251}

References aco_option::args.

Referenced by timeval_str2struct().

◆ aco_option_get_flags()

unsigned int aco_option_get_flags ( const struct aco_option option)

Read the flags of a config option - useful when using a custom callback for a config option.

Since
12
Parameters
optionPointer to the aco_option struct
Return values
valueof the flags on the config option

Definition at line 243 of file config_options.c.

244{
245 return option->flags;
246}

References aco_option::flags.

Referenced by option_handler_parkedfeature().

◆ aco_option_register_deprecated()

int aco_option_register_deprecated ( struct aco_info info,
const char *  name,
struct aco_type **  types,
const char *  aliased_to 
)

Register a deprecated (and aliased) config option.

Parameters
infoA pointer to the aco_info struct
nameThe name of the deprecated option
typesAn array of valid option types for matching categories to the correct struct type
aliased_toThe name of the option that this deprecated option matches to
Return values
0Success
-1Failure

Definition at line 217 of file config_options.c.

218{
219 struct aco_option *opt;
220
222 return -1;
223 }
224
226 if (!opt) {
227 return -1;
228 }
229
230 opt->name = name;
231 opt->aliased_to = aliased_to;
232 opt->deprecated = 1;
233 opt->match_type = ACO_EXACT;
234
235 if (link_option_to_types(info, types, opt)) {
236 ao2_ref(opt, -1);
237 return -1;
238 }
239
240 return 0;
241}
static force_inline int attribute_pure ast_strlen_zero(const char *s)
Definition: strings.h:65
unsigned char deprecated
const char * aliased_to

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

Referenced by AST_TEST_DEFINE().

◆ aco_pending_config()

void * aco_pending_config ( struct aco_info info)

Get pending config changes.

Note
This will most likely be called from the pre_apply_config callback function
Parameters
infoAn initialized aco_info
Return values
NULLerror
non-NULLA pointer to the user-defined config object with un-applied changes

Definition at line 103 of file config_options.c.

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

References ast_log, sip_to_pjsip::info(), LOG_ERROR, and NULL.

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

◆ aco_process_ast_config()

enum aco_process_status aco_process_ast_config ( struct aco_info info,
struct aco_file file,
struct ast_config cfg 
)

Process config info from an ast_config via options registered with an aco_info.

Parameters
infoThe aco_info to be used for handling the config
fileThe file attached to aco_info that the config represents
cfgA pointer to a loaded ast_config to parse
Return values
ACO_PROCESS_OKSuccess
ACO_PROCESS_ERRORFailure

Definition at line 617 of file config_options.c.

618{
619 if (!info->internal) {
620 ast_log(LOG_ERROR, "Attempt to process %s with uninitialized aco_info\n", file->filename);
621 return ACO_PROCESS_ERROR;
622 }
623
624 if (!(info->internal->pending = info->snapshot_alloc())) {
625 ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", file->filename);
626 goto error;
627 }
628
630 goto error;
631 }
632
633 if (info->pre_apply_config && info->pre_apply_config()) {
634 goto error;
635 }
636
637 if (apply_config(info)) {
638 goto error;
639 };
640
641 ao2_cleanup(info->internal->pending);
642 info->internal->pending = NULL;
643 return ACO_PROCESS_OK;
644
645error:
646 ao2_cleanup(info->internal->pending);
647 info->internal->pending = NULL;
648
649 return ACO_PROCESS_ERROR;
650}
#define ao2_cleanup(obj)
Definition: astobj2.h:1934
static int apply_config(struct aco_info *info)
static enum aco_process_status internal_process_ast_config(struct aco_info *info, struct aco_file *file, struct ast_config *cfg)

References ACO_PROCESS_ERROR, ACO_PROCESS_OK, ao2_cleanup, apply_config(), ast_log, error(), make_ari_stubs::file, sip_to_pjsip::info(), internal_process_ast_config(), LOG_ERROR, and NULL.

◆ aco_process_category_options()

int aco_process_category_options ( struct aco_type type,
struct ast_config cfg,
const char *  cat,
void *  obj 
)

Parse each option defined in a config category.

Parameters
typeThe aco_type with the options for parsing
cfgThe ast_config being parsed
catThe config category being parsed
objThe user-defined config object that will store the parsed config items
Return values
0Success
-1Failure

Definition at line 805 of file config_options.c.

806{
807 struct ast_variable *var;
808
809 for (var = ast_variable_browse(cfg, cat); var; var = var->next) {
810 if (aco_process_var(type, cat, var, obj)) {
811 return -1;
812 }
813 }
814
815 return 0;
816}
#define var
Definition: ast_expr2f.c:605
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.
struct ast_variable * ast_variable_browse(const struct ast_config *config, const char *category_name)
Definition: extconf.c:1215
Structure for variables, used for configurations and for channel variables.

References aco_process_var(), ast_variable_browse(), type, and var.

Referenced by process_category().

◆ aco_process_config()

enum aco_process_status aco_process_config ( struct aco_info info,
int  reload 
)

Process a config info via the options registered with an aco_info.

Parameters
infoThe config_options_info to be used for handling the config
reloadNon-zero if this is for a reload.
Return values
ACO_PROCESS_OKSuccess
ACO_PROCESS_ERRORFailure
ACO_PROCESS_UNCHANGEDNo change due to unedited config file
Examples
app_skel.c.

Definition at line 652 of file config_options.c.

653{
654 struct ast_config *cfg;
655 struct ast_flags cfg_flags = { reload ? CONFIG_FLAG_FILEUNCHANGED : 0, };
656 int res = ACO_PROCESS_OK;
657 int file_count = 0;
658 struct aco_file *file;
659
660 if (!info->internal) {
661 ast_log(LOG_ERROR, "Attempting to process uninitialized aco_info\n");
662 return ACO_PROCESS_ERROR;
663 }
664
665 if (!(info->files[0])) {
666 ast_log(LOG_ERROR, "No filename given, cannot proceed!\n");
667 return ACO_PROCESS_ERROR;
668 }
669
670 if (!(info->internal->pending = info->snapshot_alloc())) {
671 ast_log(LOG_ERROR, "In %s: Could not allocate temporary objects\n", info->module);
672 return ACO_PROCESS_ERROR;
673 }
674
675 while (res != ACO_PROCESS_ERROR && (file = info->files[file_count++])) {
676 const char *filename = file->filename;
677 struct aco_type *match;
678 int i;
679
680 /* set defaults for global objects */
681 for (i = 0, match = file->types[i]; match; match = file->types[++i]) {
682 void **field = info->internal->pending + match->item_offset;
683
684 if (match->type == ACO_IGNORE) {
685 continue;
686 }
687
688 if (match->type != ACO_GLOBAL || !*field) {
689 continue;
690 }
691
692 if (aco_set_defaults(match, match->category, *field)) {
693 ast_log(LOG_ERROR, "In %s: Setting defaults for %s failed\n", file->filename, match->category);
694 res = ACO_PROCESS_ERROR;
695 break;
696 }
697 }
698
699 if (res == ACO_PROCESS_ERROR) {
700 break;
701 }
702
703try_alias:
704 cfg = ast_config_load(filename, cfg_flags);
705 if (!cfg || cfg == CONFIG_STATUS_FILEMISSING) {
706 if (file->alias && strcmp(file->alias, filename)) {
707 filename = file->alias;
708 goto try_alias;
709 }
710 ast_log(LOG_ERROR, "Unable to load config file '%s'\n", file->filename);
711 res = ACO_PROCESS_ERROR;
712 break;
713 } else if (cfg == CONFIG_STATUS_FILEUNCHANGED) {
714 ast_debug(1, "%s was unchanged\n", file->filename);
716 continue;
717 } else if (cfg == CONFIG_STATUS_FILEINVALID) {
718 ast_log(LOG_ERROR, "Contents of %s are invalid and cannot be parsed\n",
719 file->filename);
720 res = ACO_PROCESS_ERROR;
721 break;
722 }
723
724 /* A file got loaded. */
725 if (reload) {
726 /* Must do any subsequent file loads unconditionally. */
727 reload = 0;
729
730 if (file_count != 1) {
731 /*
732 * Must restart loading to load all config files since a file
733 * after the first one changed.
734 */
735 file_count = 0;
736 } else {
738 }
739 } else {
741 }
743 }
744
745 if (res != ACO_PROCESS_OK) {
746 goto end;
747 }
748
749 if (info->pre_apply_config && info->pre_apply_config()) {
750 res = ACO_PROCESS_ERROR;
751 goto end;
752 }
753
754 if (apply_config(info)) {
755 res = ACO_PROCESS_ERROR;
756 goto end;
757 }
758
759 if (info->post_apply_config) {
760 info->post_apply_config();
761 }
762
763end:
764 ao2_cleanup(info->internal->pending);
765 info->internal->pending = NULL;
766
767 return res;
768}
static int match(struct ast_sockaddr *addr, unsigned short callno, unsigned short dcallno, const struct chan_iax2_pvt *cur, int check_dcallno)
Definition: chan_iax2.c:2362
int aco_set_defaults(struct aco_type *type, const char *category, void *obj)
Set all default options of obj.
char * end
Definition: eagi_proxy.c:73
#define ast_config_load(filename, flags)
Load a config file.
#define CONFIG_STATUS_FILEMISSING
#define CONFIG_STATUS_FILEUNCHANGED
#define CONFIG_STATUS_FILEINVALID
void ast_config_destroy(struct ast_config *cfg)
Destroys a config.
Definition: extconf.c:1289
@ CONFIG_FLAG_FILEUNCHANGED
#define ast_debug(level,...)
Log a DEBUG message.
static int reload(void)
const char * filename
Structure used to handle boolean flags.
Definition: utils.h:199
#define ast_clear_flag(p, flag)
Definition: utils.h:77

References ACO_GLOBAL, ACO_IGNORE, ACO_PROCESS_ERROR, ACO_PROCESS_OK, ACO_PROCESS_UNCHANGED, aco_set_defaults(), ao2_cleanup, apply_config(), ast_clear_flag, ast_config_destroy(), ast_config_load, ast_debug, ast_log, CONFIG_FLAG_FILEUNCHANGED, CONFIG_STATUS_FILEINVALID, CONFIG_STATUS_FILEMISSING, CONFIG_STATUS_FILEUNCHANGED, end, make_ari_stubs::file, aco_file::filename, sip_to_pjsip::info(), internal_process_ast_config(), LOG_ERROR, match(), NULL, and reload().

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

◆ aco_process_var()

int aco_process_var ( struct aco_type type,
const char *  cat,
struct ast_variable var,
void *  obj 
)

Parse a single ast_variable and apply it to an object.

Note
This function can be used to build up an object by repeatedly passing in the config variable name and values that would be found in a config file. This can be useful if the object is to be populated by a dialplan function, for example.
Parameters
typeThe aco_type associated with the object
catThe category to use
varA variable to apply to the object
objA pointer to the object to be configured
Return values
0Success
-1Failure

Definition at line 769 of file config_options.c.

770{
771 RAII_VAR(struct aco_option *, opt, aco_option_find(type, var->name), ao2_cleanup);
772 if (opt && opt->deprecated && !ast_strlen_zero(opt->aliased_to)) {
773 const char *alias = ast_strdupa(opt->aliased_to);
774 ast_log(LOG_WARNING, "At line %d of %s option '%s' is deprecated. Use '%s' instead\n", var->lineno, var->file, var->name, alias);
775 ao2_ref(opt, -1);
776 opt = aco_option_find(type, alias);
777 }
778
779 if (!opt) {
780 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);
781 return -1;
782 }
783
784 if (!opt->handler) {
785 /* It should be impossible for an option to not have a handler */
786 ast_log(LOG_ERROR, "BUG! Somehow a config option for %s/%s was created with no handler!\n", cat, var->name);
787 return -1;
788 }
789
790#ifdef AST_DEVMODE
791 if (opt->doc_unavailable) {
792 ast_log(LOG_ERROR, "Config option '%s' of type '%s' is not completely documented and can not be set\n", var->name, type->name);
793 return -1;
794 }
795#endif
796
797 if (opt->handler(opt, var, obj)) {
798 ast_log(LOG_ERROR, "Error parsing %s=%s at line %d of %s\n", var->name, var->value, var->lineno, var->file);
799 return -1;
800 }
801
802 return 0;
803}
#define ast_strdupa(s)
duplicate a string in memory from the stack
Definition: astmm.h:298
static struct aco_option * aco_option_find(struct aco_type *type, const char *name)
#define LOG_WARNING
#define RAII_VAR(vartype, varname, initval, dtor)
Declare a variable that will call a destructor function when it goes out of scope.
Definition: utils.h:941

References aco_option_find(), ao2_cleanup, ao2_ref, ast_log, ast_strdupa, ast_strlen_zero(), LOG_ERROR, LOG_WARNING, RAII_VAR, type, and var.

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

◆ aco_set_defaults()

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

Set all default options of obj.

Parameters
typeThe aco_type with the options
categoryThe configuration category from which obj is being configured
objThe object being configured
Return values
0Success
-1Failure

Definition at line 924 of file config_options.c.

925{
926 struct aco_option *opt;
927 struct ao2_iterator iter;
928
929 if (!type->internal) {
930 return -1;
931 }
932
933 iter = ao2_iterator_init(type->internal->opts, 0);
934
935 while ((opt = ao2_iterator_next(&iter))) {
937
938 if (ast_strlen_zero(opt->default_val)) {
939 ao2_ref(opt, -1);
940 continue;
941 }
942 if (!(var = ast_variable_new(opt->name, opt->default_val, ""))) {
943 ao2_ref(opt, -1);
945 return -1;
946 }
947 if (opt->handler(opt, var, obj)) {
948 ast_log(LOG_ERROR, "Unable to set default for %s, %s=%s\n", category, var->name, var->value);
949 ao2_ref(opt, -1);
951 return -1;
952 }
953 ao2_ref(opt, -1);
954 }
956
957 return 0;
958}
#define ao2_iterator_next(iter)
Definition: astobj2.h:1911
struct ao2_iterator ao2_iterator_init(struct ao2_container *c, int flags) attribute_warn_unused_result
Create an iterator for a container.
void ao2_iterator_destroy(struct ao2_iterator *iter)
Destroy a container iterator.
#define ast_variable_new(name, value, filename)
void ast_variables_destroy(struct ast_variable *var)
Free variable list.
Definition: extconf.c:1262
When we need to walk through a container, we use an ao2_iterator to keep track of the current positio...
Definition: astobj2.h:1821

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, LOG_ERROR, aco_option::name, NULL, RAII_VAR, type, and var.

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