[asterisk-commits] twilson: trunk r368663 - in /trunk: include/asterisk/ main/ tests/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Thu Jun 7 10:43:46 CDT 2012
Author: twilson
Date: Thu Jun 7 10:43:37 2012
New Revision: 368663
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=368663
Log:
Add default handler documentation and standardize acl handler
Added documentation describing what flags and arguments to pass to
aco_option_register for default option types. Also changed the ACL
handler to use the flags parameter to differentiate between "permit"
and "deny" instead of adding an additional vararg parameter.
Review: https://reviewboard.asterisk.org/r/1969/
Modified:
trunk/include/asterisk/config_options.h
trunk/main/config_options.c
trunk/tests/test_config.c
Modified: trunk/include/asterisk/config_options.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/config_options.h?view=diff&rev=368663&r1=368662&r2=368663
==============================================================================
--- trunk/include/asterisk/config_options.h (original)
+++ trunk/include/asterisk/config_options.h Thu Jun 7 10:43:37 2012
@@ -206,26 +206,171 @@
*/
void aco_info_destroy(struct aco_info *info);
-/*! \brief The option types with default handlers
+/*! \brief 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, *in the order
- * they must be passed* to aco_option_register. The fields
- * are located in the args array in the ast_config_option passed to
- * the default handler function.
- * */
+ * option below is commented with the field types, additional arguments
+ * and example usage with aco_option_register
+ */
enum aco_option_type {
- OPT_ACL_T, /*!< fields: struct ast_ha * */
- OPT_BOOL_T, /*!< fields: unsigned int */
- OPT_CODEC_T, /*!< fields: struct ast_codec pref, struct ast_format_cap * */
- OPT_CUSTOM_T, /*!< fields: none */
- OPT_DOUBLE_T, /*!< fields: double */
- OPT_INT_T, /*!< fields: int */
- OPT_SOCKADDR_T, /*!< fields: struct ast_sockaddr */
- OPT_STRINGFIELD_T, /*!< fields: ast_string_field */
- OPT_UINT_T, /*!< fields: unsigned int */
+ /*! \brief Type for default option handler for ACLs
+ * \note aco_option_register flags:
+ * non-zero : "permit"
+ * 0 : "deny"
+ * aco_option_register varargs:
+ * FLDSET macro with the field of type struct ast_ha *.
+ *
+ * Example:
+ * {code}
+ * struct test_item {
+ * struct ast_ha *ha;
+ * };
+ * aco_option_register(&cfg_info, "permit", ACO_EXACT, my_types, NULL, OPT_ACL_T, 1, FLDSET(struct test_item, ha));
+ * aco_option_register(&cfg_info, "deny", ACO_EXACT, my_types, NULL, OPT_ACL_T, 0, FLDSET(struct test_item, ha));
+ * {code}
+ */
+ OPT_ACL_T,
+
+ /*! \brief Type for default option handler for bools (ast_true/ast_false)
+ * \note aco_option_register flags:
+ * non-zero : process via ast_true
+ * 0 : process via ast_false
+ * aco_option_register varargs:
+ * FLDSET macro with the field of type int. It is important to note that the field
+ * cannot be a bitfield. If bitfields are required, they must be set via a custom handler.
+ *
+ * Example:
+ * {code}
+ * struct test_item {
+ * int enabled;
+ * };
+ aco_option_register(&cfg_info, "enabled", ACO_EXACT, my_types, "no", OPT_BOOL_T, 1, FLDSET(struct test_item, enabled));
+ * {endcode}
+ */
+ OPT_BOOL_T,
+
+ /*! \brief Type for default option handler for codec preferences/capabilities
+ * \note aco_option_register flags:
+ * non-zero : This is an "allow" style option
+ * 0 : This is a "disallow" style option
+ * aco_option_register varargs:
+ * FLDSET macro with fields representing a struct ast_codec_pref and a struct ast_format_cap *
+ *
+ * Example:
+ * {code}
+ * struct test_item {
+ * struct ast_codec_pref pref;
+ * struct ast_format cap *cap;
+ * };
+ * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, pref, cap));
+ * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, pref, cap));
+ */
+ OPT_CODEC_T,
+
+ /*! \brief Type for a custom (user-defined) option handler */
+ OPT_CUSTOM_T,
+
+ /*! \brief Type for default option handler for doubles
+ *
+ * \note aco_option_register flags:
+ * See flags available for use with the PARSE_DOUBLE type for the ast_parse_arg function
+ * aco_option_register varargs:
+ * FLDSET macro with the field of type double
+ *
+ * Example:
+ * struct test_item {
+ * double dub;
+ * };
+ * {code}
+ * aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, my_types, "3", OPT_DOUBLE_T, FLDSET(struct test_item, dub));
+ * {endcode}
+ */
+ OPT_DOUBLE_T,
+
+ /*! \brief Type for default option handler for signed integers
+ *
+ * \note aco_option_register flags:
+ * See flags available for use with the PARSE_INT32 type for the ast_parse_arg function
+ * aco_option_register varargs:
+ * FLDSET macro with the field of type int32_t
+ * The remaining varargs for should be arguments compatible with the varargs for the
+ * ast_parse_arg function with the PARSE_INT32 type and the flags passed in the
+ * aco_option_register flags parameter.
+ *
+ * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
+ * contains an invalid value, it is better to let the config loading fail with warnings so that
+ * the problem is fixed by the administrator.
+ *
+ * Example:
+ * struct test_item {
+ * int32_t intopt;
+ * };
+ * {code}
+ * aco_option_register(&cfg_info, "intopt", ACO_EXACT, my_types, "3", OPT_INT_T, PARSE_IN_RANGE, FLDSET(struct test_item, intopt), -10, 10);
+ * {endcode}
+ */
+ OPT_INT_T,
+
+ /*! \brief Type for default handler for ast_sockaddrs
+ *
+ * \note aco_option_register flags:
+ * See flags available for use with the PARSE_ADDR type for the ast_parse_arg function
+ * aco_option_register varargs:
+ * FLDSET macro with the field being of type struct ast_sockaddr.
+ *
+ * Example:
+ * {code}
+ * struct test_item {
+ * struct ast_sockaddr addr;
+ * };
+ * aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, my_types, "0.0.0.0:1234", OPT_SOCKADDR_T, 0, FLDSET(struct test_item, addr));
+ * {endcode}
+ */
+ OPT_SOCKADDR_T,
+
+ /*! \brief Type for default option handler for stringfields
+ * \note aco_option_register flags:
+ * none
+ * aco_option_register varargs:
+ * STRFLDSET macro with the field being the field created by AST_STRING_FIELD
+ *
+ * Example:
+ * {code}
+ * struct test_item {
+ * AST_DECLARE_STRING_FIELDS(
+ * AST_STRING_FIELD(thing);
+ * );
+ * };
+ * aco_option_register(&cfg_info, "thing", ACO_EXACT, my_types, NULL, OPT_STR_T, 0, STRFLDSET(struct test_item, thing));
+ * {endcode}
+ */
+ OPT_STRINGFIELD_T,
+
+ /*! \brief Type for default option handler for unsigned integers
+ *
+ * \note aco_option_register flags:
+ * See flags available for use with the PARSE_UINT32 type for the ast_parse_arg function
+ * aco_option_register varargs:
+ * FLDSET macro with the field of type uint32_t
+ * The remaining varargs for should be arguments compatible with the varargs for the
+ * ast_parse_arg function with the PARSE_UINT32 type and the flags passed in the
+ * aco_option_register flags parameter.
+ *
+ * \note In most situations, it is preferable to not pass the PARSE_DEFAULT flag. If a config
+ * contains an invalid value, it is better to let the config loading fail with warnings so that
+ * the problem is fixed by the administrator.
+ *
+ * Example:
+ * struct test_item {
+ * int32_t intopt;
+ * };
+ * {code}
+ * aco_option_register(&cfg_info, "uintopt", ACO_EXACT, my_types, "3", OPT_UINT_T, PARSE_IN_RANGE, FLDSET(struct test_item, uintopt), 1, 10);
+ * {endcode}
+ */
+ OPT_UINT_T,
};
/*! \brief A callback function for handling a particular option
Modified: trunk/main/config_options.c
URL: http://svnview.digium.com/svn/asterisk/trunk/main/config_options.c?view=diff&rev=368663&r1=368662&r2=368663
==============================================================================
--- trunk/main/config_options.c (original)
+++ trunk/main/config_options.c Thu Jun 7 10:43:37 2012
@@ -596,7 +596,12 @@
return 0;
}
-/* default config option handlers */
+/* Default config option handlers */
+
+/*! \brief Default option handler for signed integers
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int int_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj) {
int *field = (int *)(obj + opt->args[0]);
unsigned int flags = PARSE_INT32 | opt->flags;
@@ -623,6 +628,10 @@
return res;
}
+/*! \brief Default option handler for unsigned integers
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int uint_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj) {
unsigned int *field = (unsigned int *)(obj + opt->args[0]);
unsigned int flags = PARSE_INT32 | opt->flags;
@@ -649,27 +658,40 @@
return res;
}
+/*! \brief Default option handler for doubles
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int double_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj) {
double *field = (double *)(obj + opt->args[0]);
return ast_parse_arg(var->value, PARSE_DOUBLE | opt->flags, field);
}
+/*! \brief Default handler for ACLs
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int acl_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj) {
struct ast_ha **ha = (struct ast_ha **)(obj + opt->args[0]);
- const char *permit = (const char *) opt->args[1];
int error = 0;
- *ha = ast_append_ha(permit, var->value, *ha, &error);
+ *ha = ast_append_ha(opt->flags ? "permit" : "deny", var->value, *ha, &error);
return error;
}
-/* opt->args[0] = struct ast_codec_pref, opt->args[1] struct ast_format_cap * */
+/*! \brief Default option handler for codec preferences/capabilities
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int codec_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj) {
struct ast_codec_pref *pref = (struct ast_codec_pref *)(obj + opt->args[0]);
struct ast_format_cap **cap = (struct ast_format_cap **)(obj + opt->args[1]);
return ast_parse_allow_disallow(pref, *cap, var->value, opt->flags);
}
-/* opt->args[0] = ast_string_field, opt->args[1] = field_mgr_pool, opt->args[2] = field_mgr */
+/*! \brief Default option handler for stringfields
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int stringfield_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj)
{
ast_string_field *field = (const char **)(obj + opt->args[0]);
@@ -679,6 +701,10 @@
return 0;
}
+/*! \brief Default option handler for bools (ast_true/ast_false)
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int bool_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj)
{
unsigned int *field = (unsigned int *)(obj + opt->args[0]);
@@ -686,6 +712,10 @@
return 0;
}
+/*! \brief Default handler for ast_sockaddrs
+ * \note For a description of the opt->flags and opt->args values, see the documentation for
+ * enum aco_option_type in config_options.h
+ */
static int sockaddr_handler_fn(const struct aco_option *opt, struct ast_variable *var, void *obj)
{
struct ast_sockaddr *field = (struct ast_sockaddr *)(obj + opt->args[0]);
Modified: trunk/tests/test_config.c
URL: http://svnview.digium.com/svn/asterisk/trunk/tests/test_config.c?view=diff&rev=368663&r1=368662&r2=368663
==============================================================================
--- trunk/tests/test_config.c (original)
+++ trunk/tests/test_config.c Thu Jun 7 10:43:37 2012
@@ -805,8 +805,8 @@
aco_option_register(&cfg_info, "doubleopt", ACO_EXACT, config_test_conf.types, DOUBLE_DEFAULT, OPT_DOUBLE_T, 0, FLDSET(struct test_item, doubleopt));
aco_option_register(&cfg_info, "sockaddropt", ACO_EXACT, config_test_conf.types, SOCKADDR_DEFAULT, OPT_SOCKADDR_T, 0, FLDSET(struct test_item, sockaddropt));
aco_option_register(&cfg_info, "boolopt", ACO_EXACT, config_test_conf.types, BOOL_DEFAULT, OPT_BOOL_T, 1, FLDSET(struct test_item, boolopt));
- aco_option_register(&cfg_info, "aclpermitopt", ACO_EXACT, config_test_conf.types, ACL_DEFAULT, OPT_ACL_T, 1, FLDSET(struct test_item, aclopt), "permit");
- aco_option_register(&cfg_info, "acldenyopt", ACO_EXACT, config_test_conf.types, ACL_DEFAULT, OPT_ACL_T, 0, FLDSET(struct test_item, aclopt), "deny");
+ aco_option_register(&cfg_info, "aclpermitopt", ACO_EXACT, config_test_conf.types, ACL_DEFAULT, OPT_ACL_T, 1, FLDSET(struct test_item, aclopt));
+ aco_option_register(&cfg_info, "acldenyopt", ACO_EXACT, config_test_conf.types, ACL_DEFAULT, OPT_ACL_T, 0, FLDSET(struct test_item, aclopt));
aco_option_register(&cfg_info, "codecopt", ACO_EXACT, config_test_conf.types, CODEC_DEFAULT, OPT_CODEC_T, 1, FLDSET(struct test_item, codecprefopt, codeccapopt));
aco_option_register(&cfg_info, "stropt", ACO_EXACT, config_test_conf.types, STR_DEFAULT, OPT_STRINGFIELD_T, 0, STRFLDSET(struct test_item, stropt));
aco_option_register_custom(&cfg_info, "customopt", ACO_EXACT, config_test_conf.types, CUSTOM_DEFAULT, customopt_handler, 0);
More information about the asterisk-commits
mailing list