config_options.h

Go to the documentation of this file.
00001 /*
00002  * Asterisk -- An open source telephony toolkit.
00003  *
00004  * Copyright (C) 2012, Digium, Inc.
00005  *
00006  * Mark Spencer <markster@digium.com>
00007  *
00008  * See http://www.asterisk.org for more information about
00009  * the Asterisk project. Please do not directly contact
00010  * any of the maintainers of this project for assistance;
00011  * the project provides a web site, mailing lists and IRC
00012  * channels for your use.
00013  *
00014  * This program is free software, distributed under the terms of
00015  * the GNU General Public License Version 2. See the LICENSE file
00016  * at the top of the source tree.
00017  */
00018 
00019 /*! \file
00020  * \brief Configuration option-handling
00021  * \author Terry Wilson <twilson@digium.com>
00022  */
00023 
00024 #ifndef _ASTERISK_CONFIG_OPTIONS_H
00025 #define _ASTERISK_CONFIG_OPTIONS_H
00026 
00027 #if defined(__cplusplus) || defined(c_plusplus)
00028 extern "C" {
00029 #endif
00030 
00031 #include <regex.h>
00032 
00033 #include "asterisk/config.h"
00034 #include "asterisk/astobj2.h"
00035 
00036 struct aco_option;
00037 struct aco_info_internal;
00038 struct aco_type_internal;
00039 
00040 enum aco_type_t {
00041    ACO_GLOBAL,
00042    ACO_ITEM,
00043 };
00044 
00045 /*! \brief Whether a category regex is a blackist or a whitelist */
00046 enum aco_category_op {
00047    ACO_BLACKLIST = 0,
00048    ACO_WHITELIST,
00049 };
00050 
00051 /*! \brief What kind of matching should be done on an option name */
00052 enum aco_matchtype {
00053    ACO_EXACT = 1,
00054    ACO_REGEX,
00055 };
00056 
00057 /*! Callback functions for option parsing via aco_process_config() */
00058 
00059 /*! \brief Allocate a configurable ao2 object
00060  * \param category The config category the object is being generated for
00061  * \retval NULL error
00062  * \retval non-NULL a new configurable ao2 object
00063  */
00064 typedef void *(*aco_type_item_alloc)(const char *category);
00065 
00066 /*! \brief Find a item given a category and container of items
00067  * \param container The container to search for the item
00068  * \param category The category associated with the item
00069  * \retval non-NULL item from the container
00070  * \retval NULL item does not exist in container
00071  */
00072 typedef void *(*aco_type_item_find)(struct ao2_container *newcontainer, const char *category);
00073 
00074 /*! \brief Callback function that is called after a config object is initialized with defaults
00075  *
00076  * \note This callback is called during config processing after a new config is allocated and
00077  * and defaults applied but before values from the config are read. This callback could be used
00078  * to merge in settings inherited from the global settings if necessary, despite that being a
00079  * bad thing to do!
00080  *
00081  * \param newitem The newly allocated config object with defaults populated
00082  * \retval 0 succes, continue processing
00083  * \retval non-zero failure, stop processing
00084  */
00085 typedef int (*aco_type_item_pre_process)(void *newitem);
00086 
00087 /*! \brief Callback function that is called after config processing, but before linking
00088  *
00089  * \note This callback is called after config processing, but before linking the object
00090  * in the config container. This callback can be used to verify that all settings make
00091  * sense together, that required options have been set, etc.
00092  *
00093  * \param newitem The newly configured object
00094  * \retval 0 success, continue processing
00095  * \retval non-zero failure, stop processing
00096  */
00097 typedef int (*aco_type_prelink)(void *newitem);
00098 
00099 /*! \brief A function for determining whether the value for the matchfield in an aco_type is sufficient for a match
00100  * \param text The value of the option
00101  * \retval -1 The value is sufficient for a match
00102  * \retval 0 The value is not sufficient for a match
00103  */
00104 typedef int (*aco_matchvalue_func)(const char *text);
00105 
00106 /*! \struct aco_type
00107  * \brief Type information about a category-level configurable object
00108  */
00109 struct aco_type {
00110    /* common stuff */
00111    enum aco_type_t type;   /*!< Whether this is a global or item type */
00112    const char *name;       /*!< The name of this type (must match XML documentation) */
00113    const char *category;   /*!< A regular expression for matching categories to be allowed or denied */
00114    const char *matchfield; /*!< An option name to match for this type (i.e. a 'type'-like column) */
00115    const char *matchvalue; /*!< The value of the option to require for matching (i.e. 'peer' for type= in sip.conf) */
00116    aco_matchvalue_func matchfunc;       /*!< A function for determing whether the option value matches (i.e. hassip= requires ast_true()) */
00117    enum aco_category_op category_match; /*!< Whether the following category regex is a whitelist or blacklist */
00118    size_t item_offset;                  /*!< The offset in the config snapshot for the global config or item config container */
00119    unsigned int hidden;  /*!< Type is for internal purposes only and it and all options should not be visible to users */
00120 
00121    /* non-global callbacks */
00122    aco_type_item_alloc item_alloc;         /*!< An allocation function for item associated with this type */
00123    aco_type_item_find item_find;           /*!< A callback function to find an existing item in a particular container */
00124    aco_type_item_pre_process item_pre_process; /*!< An optional callback function that is called after defaults are applied, but before config processing */
00125    aco_type_prelink item_prelink;          /*!< An optional callback function that is called after config processing, but before applying changes */
00126    struct aco_type_internal *internal;
00127 };
00128 
00129 /*! \brief A callback function to run just prior to applying config changes
00130  * \retval 0 Success
00131  * \retval non-zero Failure. Changes not applied
00132  */
00133 typedef int (*aco_pre_apply_config)(void);
00134 
00135 /*! \brief A callback function called only if config changes have been applied
00136  *
00137  * \note If a config file has not been edited prior to performing a reload, this
00138  * callback will not be called.
00139  */
00140 typedef void (*aco_post_apply_config)(void);
00141 
00142 /*! \brief A callback function for allocating an object to hold all config objects
00143  * \retval NULL error
00144  * \retval non-NULL a config object container
00145  */
00146 typedef void *(*aco_snapshot_alloc)(void);
00147 
00148 /*! \brief The representation of a single configuration file to be processed */
00149 struct aco_file {
00150    const char *filename;       /*!< The filename to be processed */
00151    const char *alias;          /*!< An alias filename to be tried if 'filename' cannot be found */
00152    const char **preload;       /*!< A null-terminated ordered array of categories to be loaded first */
00153    const char *skip_category;  /*!< A regular expression of categories to skip in the file. Use when a file is processed by multiple modules */
00154    struct aco_type *types[];   /*!< The list of types for this config. Required. Use a sentinel! */
00155 };
00156 
00157 struct aco_info {
00158    const char *module; /*!< The name of the module whose config is being processed */
00159    int hidden:1;                /*!< If enabled, this config item is hidden from users */
00160    aco_pre_apply_config pre_apply_config; /*!< A callback called after processing, but before changes are applied */
00161    aco_post_apply_config post_apply_config;/*!< A callback called after changes are applied */
00162    aco_snapshot_alloc snapshot_alloc;     /*!< Allocate an object to hold all global configs and item containers */
00163    struct ao2_global_obj *global_obj;     /*!< The global object array that holds the user-defined config object */
00164    struct aco_info_internal *internal;
00165    struct aco_file *files[];    /*!< An array of aco_files to process */
00166 };
00167 
00168 /*! \brief A helper macro to ensure that aco_info types always have a sentinel */
00169 #define ACO_TYPES(...) { __VA_ARGS__, NULL, }
00170 #define ACO_FILES(...) { __VA_ARGS__, NULL, }
00171 
00172 /*! \brief Get pending config changes
00173  * \note This will most likely be called from the pre_apply_config callback function
00174  * \param info An initialized aco_info
00175  * \retval NULL error
00176  * \retval non-NULL A pointer to the user-defined config object with un-applied changes
00177  */
00178 void *aco_pending_config(struct aco_info *info);
00179 
00180 /*! \def CONFIG_INFO_STANDARD
00181  * \brief Declare an aco_info struct with default module and preload values
00182  * \param name The name of the struct
00183  * \param arr The global object array for holding the user-defined config object
00184  * \param alloc The allocater for the user-defined config object
00185  *
00186  * Example:
00187  * \code
00188  * static AO2_GLOBAL_OBJ_STATIC(globals, 1);
00189  * CONFIG_INFO_STANDARD(cfg_info, globals, skel_config_alloc,
00190  *     .pre_apply_config = skel_pre_apply_config,
00191  *     .files = { &app_skel_conf, NULL },
00192  * );
00193  * ...
00194  * if (aco_info_init(&cfg_info)) {
00195  *     return AST_MODULE_LOAD_DECLINE;
00196  * }
00197  * ...
00198  * aco_info_destroy(&cfg_info);
00199  * \endcode
00200  */
00201 #define CONFIG_INFO_STANDARD(name, arr, alloc, ...) \
00202 static struct aco_info name = { \
00203    .module = AST_MODULE, \
00204    .global_obj = &arr, \
00205    .snapshot_alloc = alloc, \
00206    __VA_ARGS__ \
00207 };
00208 
00209 #define CONFIG_INFO_CORE(mod, name, arr, alloc, ...) \
00210 static struct aco_info name = { \
00211    .module = mod, \
00212    .global_obj = &arr, \
00213    .snapshot_alloc = alloc, \
00214    __VA_ARGS__ \
00215 };
00216 
00217 #define CONFIG_INFO_TEST(name, arr, alloc, ...) \
00218 static struct aco_info name = { \
00219    .module = AST_MODULE, \
00220    .global_obj = &arr, \
00221    .snapshot_alloc = alloc, \
00222    .hidden = 1, \
00223    __VA_ARGS__ \
00224 };
00225 
00226 /*! \brief Initialize an aco_info structure
00227  * \note aco_info_destroy must be called if this succeeds
00228  * \param info The address of an aco_info struct to initialize
00229  * \retval 0 Success
00230  * \retval non-zero Failure
00231  */
00232 int aco_info_init(struct aco_info *info);
00233 
00234 /*! \brief Destroy an initialized aco_info struct
00235  * \param info The address of the aco_info struct to destroy
00236  */
00237 void aco_info_destroy(struct aco_info *info);
00238 
00239 /*! \brief The option types
00240  *
00241  * \note aco_option_register takes an option type which is used
00242  * to look up the handler for that type. Each non-custom type requires
00243  * field names for specific types in the struct being configured. Each
00244  * option below is commented with the field types, additional arguments
00245  * and example usage with aco_option_register
00246  */
00247 enum aco_option_type {
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 };
00449 
00450 /*! \brief A callback function for handling a particular option
00451  * \param opt The option being configured
00452  * \param var The config variable to use to configure \a obj
00453  * \param obj The object to be configured
00454  *
00455  * \retval 0 Parsing and recording the config value succeeded
00456  * \retval non-zero Failure. Parsing should stop and no reload applied
00457  */
00458 typedef int (*aco_option_handler)(const struct aco_option *opt, struct ast_variable *var, void *obj);
00459 
00460 /*! \brief Allocate a container to hold config options */
00461 struct ao2_container *aco_option_container_alloc(void);
00462 
00463 /*! \brief Return values for the aco_process functions
00464  */
00465 enum aco_process_status {
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 };
00470 
00471 /*! \brief Process a config info via the options registered with an aco_info
00472  *
00473  * \param info The config_options_info to be used for handling the config
00474  * \param reload Non-zero if this is for a reload.
00475  *
00476  * \retval ACO_PROCESS_OK Success
00477  * \retval ACO_PROCESS_ERROR Failure
00478  * \retval ACO_PROCESS_UNCHANGED No change due to unedited config file
00479  */
00480 enum aco_process_status aco_process_config(struct aco_info *info, int reload);
00481 
00482 /*! \brief Process config info from an ast_config via options registered with an aco_info
00483  *
00484  * \param info The aco_info to be used for handling the config
00485  * \param file The file attached to aco_info that the config represents
00486  * \param cfg A pointer to a loaded ast_config to parse
00487  *
00488  * \retval ACO_PROCESS_OK Success
00489  * \retval ACO_PROCESS_ERROR Failure
00490  */
00491 enum aco_process_status aco_process_ast_config(struct aco_info *info, struct aco_file *file, struct ast_config *cfg);
00492 
00493 /*! \brief Parse a single ast_variable and apply it to an object
00494  * \note This function can be used to build up an object by repeatedly passing in
00495  * the config variable name and values that would be found in a config file. This can
00496  * be useful if the object is to be populated by a dialplan function, for example.
00497  *
00498  * \param type The aco_type associated with the object
00499  * \param cat The category to use
00500  * \param var A variable to apply to the object
00501  * \param obj A pointer to the object to be configured
00502  *
00503  * \retval 0 Success
00504  * \retval -1 Failure
00505  */
00506 int aco_process_var(struct aco_type *type, const char *cat, struct ast_variable *var, void *obj);
00507 
00508 /*! \brief Parse each option defined in a config category
00509  * \param type The aco_type with the options for parsing
00510  * \param cfg The ast_config being parsed
00511  * \param cat The config category being parsed
00512  * \param obj The user-defined config object that will store the parsed config items
00513  *
00514  * \retval 0 Success
00515  * \retval -1 Failure
00516  */
00517 int aco_process_category_options(struct aco_type *type, struct ast_config *cfg, const char *cat, void *obj);
00518 
00519 /*! \brief Set all default options of \a obj
00520  * \param type The aco_type with the options
00521  * \param category The configuration category from which \a obj is being configured
00522  * \param obj The object being configured
00523  *
00524  * \retval 0 Success
00525  * \retval -1 Failure
00526  */
00527 int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
00528 
00529 /*! \brief register a config option
00530  *
00531  * \note this should probably only be called by one of the aco_option_register* macros
00532  *
00533  * \param info The aco_info holding this module's config information
00534  * \param name The name of the option
00535  * \param match_type
00536  * \param types An array of valid option types for matching categories to the correct struct type
00537  * \param default_val The default value of the option in the same format as defined in a config file
00538  * \param type The option type (only for default handlers)
00539  * \param handler The handler function for the option (only for non-default types)
00540  * \param flags a type specific flags, stored in the option and available to the handler
00541  * \param no_doc if non-zero, this option should not have documentation
00542  * \param argc The number for variadic arguments
00543  * \param ... field offsets to store for default handlers
00544  *
00545  * \retval 0 success
00546  * \retval -1 failure
00547  */
00548 int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types,
00549    const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc, ...);
00550 
00551 /*! \brief Register a config option
00552  * \param info A pointer to the aco_info struct
00553  * \param name The name of the option
00554  * \param matchtype
00555  * \param types An array of valid option types for matching categories to the correct struct type
00556  * \param default_val The default value of the option in the same format as defined in a config file
00557  * \param opt_type The option type for default option type handling
00558  * \param flags a type specific flags, stored in the option and available to the handler
00559  * \param ...
00560  *
00561  * \retval 0 Success
00562  * \retval -1 Failure
00563  */
00564 #define aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...) \
00565    __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
00566 
00567 /*! \brief Register a config option
00568  * \param info A pointer to the aco_info struct
00569  * \param name The name of the option
00570  * \param matchtype
00571  * \param types An array of valid option types for matching categories to the correct struct type
00572  * \param default_val The default value of the option in the same format as defined in a config file
00573  * \param handler The handler callback for the option
00574  * \param flags \a type specific flags, stored in the option and available to the handler
00575  *
00576  * \retval 0 Success
00577  * \retval -1 Failure
00578  */
00579 #define aco_option_register_custom(info, name, matchtype, types, default_val, handler, flags) \
00580    __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
00581 
00582 /*! \brief Register a config option with no expected documentation
00583  * \param info A pointer to the aco_info struct
00584  * \param name The name of the option
00585  * \param matchtype
00586  * \param types An array of valid option types for matching categories to the correct struct type
00587  * \param default_val The default value of the option in the same format as defined in a config file
00588  * \param handler The handler callback for the option
00589  * \param flags \a type specific flags, stored in the option and available to the handler
00590  *
00591  * \note This is used primarily with custom options that only have internal purposes
00592  * and that should be ignored by the user.
00593  *
00594  * \retval 0 Success
00595  * \retval -1 Failure
00596  */
00597 #define aco_option_register_custom_nodoc(info, name, matchtype, types, default_val, handler, flags) \
00598    __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 1, 0);
00599 
00600 /*! \brief Register a deprecated (and aliased) config option
00601  * \param info A pointer to the aco_info struct
00602  * \param name The name of the deprecated option
00603  * \param types An array of valid option types for matching categories to the correct struct type
00604  * \param aliased_to The name of the option that this deprecated option matches to
00605  *
00606  * \retval 0 Success
00607  * \retval -1 Failure
00608  */
00609 int aco_option_register_deprecated(struct aco_info *info, const char *name, struct aco_type **types, const char *aliased_to);
00610 
00611 /*!
00612  * \brief Read the flags of a config option - useful when using a custom callback for a config option
00613  * \since 12
00614  *
00615  * \param option Pointer to the aco_option struct
00616  *
00617  * \retval value of the flags on the config option
00618  */
00619 unsigned int aco_option_get_flags(const struct aco_option *option);
00620 
00621 /*!
00622  * \brief Get the offset position for an argument within a config option
00623  *
00624  * \param option Pointer to the aco_option struct
00625  * \param arg Argument number
00626  *
00627  * \retval position of the argument
00628  */
00629 intptr_t aco_option_get_argument(const struct aco_option *option, unsigned int position);
00630 
00631 /*! \note  Everything below this point is to handle converting varargs
00632  * containing field names, to varargs containing a count of args, followed
00633  * by the offset of each of the field names in the struct type that is
00634  * passed in. It is currently limited to 8 arguments, but 8 variadic
00635  * arguments, like 640K, should be good enough for anyone. If not, it is
00636  * easy to add more.
00637  *
00638  */
00639 
00640 /*!
00641  * \brief Map \a func(\a func_arg, field) across all fields including \a x
00642  * \param func The function (almost certainly offsetof) to map across the fields
00643  * \param func_arg The first argument (almost certainly a type (e.g. "struct mystruct")
00644  * \param x The first field
00645  * \param ... varargs The rest of the fields
00646  *
00647  * Example usage:
00648  * \code
00649  * struct foo {
00650  *     int a;
00651  *     char *b;
00652  *     foo *c;
00653  * };
00654  * ARGMAP(offsetof, struct foo, a, c)
00655  * \endcode
00656  *
00657  * produces the string:
00658  *
00659  * \code
00660  * 2, offsetof(struct foo, a), offsetof(struct foo, b)
00661  * \endcode
00662  * which can be passed as the varargs to some other function
00663  *
00664  * The macro isn't limited to offsetof, but that is the only purpose for
00665  * which it has been tested.
00666  *
00667  * As an example of how the processing works:
00668  * \verbatim
00669  * ARGMAP(offsetof, struct foo, a, b, c) ->
00670  * ARGMAP_(3, offsetof, struct foo, a, b, c) ->
00671  * ARGMAP_3(offsetof, struct foo, 3, a, b, c) ->
00672  * ARGMAP_2(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a)), b, c) ->
00673  * ARGMAP_1(offsetof, struct foo, ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b)), c) ->
00674  * ARGIFY(3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)) ->
00675  * 3, offsetof(struct foo, a), offsetof(struct foo, b), offsetof(struct foo, c)
00676  * \endverbatim
00677  *
00678  */
00679 #define ARGMAP(func, func_arg, x, ...) ARGMAP_(VA_NARGS(x, ##__VA_ARGS__), func, func_arg, x, __VA_ARGS__)
00680 
00681 /*! \note This is sneaky. On the very first argument, we set "in" to N, the number of arguments, so
00682  * that the accumulation both works properly for the first argument (since "in" can't be empty) and
00683  * we get the number of arguments in our varargs as a bonus
00684  */
00685 #define ARGMAP_(N, func, func_arg, x, ...) PASTE(ARGMAP_, N)(func, func_arg, N, x, __VA_ARGS__)
00686 
00687 /*! \def PASTE(arg1, arg2)
00688  * \brief Paste two arguments together, even if they are macros themselves
00689  * \note Uses two levels to handle the case where arg1 and arg2 are macros themselves
00690  */
00691 #define PASTE(arg1, arg2)  PASTE1(arg1, arg2)
00692 #define PASTE1(arg1, arg2) arg1##arg2
00693 
00694 /*! \brief Take a comma-separated list and allow it to be passed as a single argument to another macro */
00695 #define ARGIFY(...) __VA_ARGS__
00696 
00697 /*! \brief The individual field handlers for ARGMAP
00698  * \param func The function (most likely offsetof)
00699  * \param func_arg The first argument to func (most likely a type e.g. "struct my_struct")
00700  * \param in The accumulated function-mapped field names so far
00701  * \param x The next field name
00702  * \param ... varargs The rest of the field names
00703  */
00704 #define ARGMAP_1(func, func_arg, in, x, ...) ARGIFY(in, func(func_arg, x))
00705 #define ARGMAP_2(func, func_arg, in, x, ...)\
00706    ARGMAP_1(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00707 #define ARGMAP_3(func, func_arg, in, x, ...)\
00708    ARGMAP_2(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00709 #define ARGMAP_4(func, func_arg, in, x, ...)\
00710    ARGMAP_3(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00711 #define ARGMAP_5(func, func_arg, in, x, ...)\
00712    ARGMAP_4(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00713 #define ARGMAP_6(func, func_arg, in, x, ...)\
00714    ARGMAP_5(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00715 #define ARGMAP_7(func, func_arg, in, x, ...)\
00716    ARGMAP_6(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00717 #define ARGMAP_8(func, func_arg, in, x, ...)\
00718    ARGMAP_7(func, func_arg, ARGIFY(in, func(func_arg, x)), __VA_ARGS__)
00719 
00720 /*! \def VA_NARGS(...)
00721  * \brief Results in the number of arguments passed to it
00722  * \note Currently only up to 8, but expanding is easy. This macro basically counts
00723  * commas + 1. To visualize:
00724  * \verbatim
00725  * VA_NARGS(one, two, three) ->                    v
00726  * VA_NARGS1(one, two, three,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
00727  * VA_NARGS1( _1,  _2,    _3, _4, _5, _6, _7, _8,  N, ...       ) N -> 3
00728  * 
00729  * Note that VA_NARGS *does not* work when there are no arguments passed. Pasting an empty
00730  * __VA_ARGS__ with a comma like ", ##__VA_ARGS__" will delete the leading comma, but it
00731  * does not work when __VA_ARGS__ is the first argument. Instead, 1 is returned instead of 0:
00732  * 
00733  * VA_NARGS() ->                              v
00734  * VA_NARGS1(  ,  8,  7,  6,  5,  4,  3,  2,  1,  0) ->
00735  * VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8,  N) -> 1
00736  * \endverbatim
00737  */
00738 #define VA_NARGS(...) VA_NARGS1(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
00739 #define VA_NARGS1(_1, _2, _3, _4, _5, _6, _7, _8, N, ...) N
00740 
00741 /*! \def FLDSET(type, ...)
00742  * \brief Convert a struct and list of fields to an argument list of field offsets
00743  * \param type The type with the fields (e.g. "struct my_struct")
00744  * \param ... varags The fields in the struct whose offsets are needed as arguments
00745  *
00746  * For example:
00747  * \code
00748  * struct foo {int a, char b[128], char *c};
00749  * FLDSET(struct foo, a, c)
00750  * \endcode
00751  *
00752  * produces
00753  * \code
00754  * offsetof(struct foo, a), offsetof(struct foo, c)
00755  * \endcode
00756  */
00757 #define FLDSET(type, ...) FLDSET1(type, ##__VA_ARGS__)
00758 #define FLDSET1(type, ...) POPPED(ARGMAP(offsetof, type, ##__VA_ARGS__))
00759 
00760 /*! \def STRFLDSET(type, ...)
00761  * \brief Convert a struct and a list of stringfield fields to an argument list of field offsets
00762  * \note Stringfields require the passing of the field manager pool, and field manager to the
00763  * default stringfield option handler, so registering options that point to stringfields requires
00764  * this macro to be called instead of the FLDSET macro.
00765  * \param type The type with the fields (e.g. "struct my_struct")
00766  * \param ... varargs The fields in the struct whose offsets are needed as arguments
00767  */
00768 #define STRFLDSET(type, ...) FLDSET(type, __VA_ARGS__, __field_mgr_pool, __field_mgr)
00769 
00770 /*! \def CHARFLDSET(type, field)
00771  * \brief A helper macro to pass the appropriate arguments to aco_option_register for OPT_CHAR_ARRAY_T
00772  * \note This will pass the offset of the field and its length as arguments
00773  * \param type The type with the char array field (e.g. "struct my_struct")
00774  * \param field The name of char array field
00775  */
00776 #define CHARFLDSET(type, field) ARGIFY(offsetof(type, field), sizeof(((type *)0)->field))
00777 
00778 /*! \def POPPED(...)
00779  * \brief A list of arguments without the first argument
00780  * \note Used internally to remove the leading "number of arguments" argument from ARGMAP for
00781  * FLDSET. This is because a call to FLDSET may be followed by additional arguments in
00782  * aco_register_option, so the true number of arguments will possibly be different than what
00783  * ARGMAP returns.
00784  * \param ... varags A list of arguments
00785  * \verbatim
00786  * POPPED(a, b, c) -> b, c
00787  * \endverbatim
00788  */
00789 #define POPPED(...) POPPED1(__VA_ARGS__)
00790 #define POPPED1(x, ...) __VA_ARGS__
00791 
00792 #if defined(__cplusplus) || defined(c_plusplus)
00793 }
00794 #endif
00795 
00796 #endif /* _ASTERISK_CONFIG_OPTIONS_H */

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