CLI: Create ast_cli_completion_vector.
[asterisk/asterisk.git] / include / asterisk / config_options.h
index 6b44446..f4c3db1 100644 (file)
@@ -116,6 +116,7 @@ struct aco_type {
        aco_matchvalue_func matchfunc;       /*!< A function for determing whether the option value matches (i.e. hassip= requires ast_true()) */
        enum aco_category_op category_match; /*!< Whether the following category regex is a whitelist or blacklist */
        size_t item_offset;                  /*!< The offset in the config snapshot for the global config or item config container */
+       unsigned int hidden;  /*!< Type is for internal purposes only and it and all options should not be visible to users */
 
        /* non-global callbacks */
        aco_type_item_alloc item_alloc;         /*!< An allocation function for item associated with this type */
@@ -155,6 +156,7 @@ struct aco_file {
 
 struct aco_info {
        const char *module; /*!< The name of the module whose config is being processed */
+       int hidden:1;                /*!< If enabled, this config item is hidden from users */
        aco_pre_apply_config pre_apply_config; /*!< A callback called after processing, but before changes are applied */
        aco_post_apply_config post_apply_config;/*!< A callback called after changes are applied */
        aco_snapshot_alloc snapshot_alloc;     /*!< Allocate an object to hold all global configs and item containers */
@@ -212,6 +214,15 @@ static struct aco_info name = { \
        __VA_ARGS__ \
 };
 
+#define CONFIG_INFO_TEST(name, arr, alloc, ...) \
+static struct aco_info name = { \
+       .module = AST_MODULE, \
+       .global_obj = &arr, \
+       .snapshot_alloc = alloc, \
+       .hidden = 1, \
+       __VA_ARGS__ \
+};
+
 /*! \brief Initialize an aco_info structure
  * \note aco_info_destroy must be called if this succeeds
  * \param info The address of an aco_info struct to initialize
@@ -306,21 +317,20 @@ enum aco_option_type {
         */
        OPT_CHAR_ARRAY_T,
 
-       /*! \brief Type for default option handler for codec preferences/capabilities
+       /*! \brief 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 fields representing a struct ast_codec_pref and a struct ast_format_cap *
+        *   FLDSET macro with field representing 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));
+        * aco_option_register(&cfg_info, "allow", ACO_EXACT, my_types, "ulaw,alaw", OPT_CODEC_T, 1, FLDSET(struct test_item, cap));
+        * aco_option_register(&cfg_info, "disallow", ACO_EXACT, my_types, "all", OPT_CODEC_T, 0, FLDSET(struct test_item, cap));
         * {endcode}
         */
        OPT_CODEC_T,
@@ -435,6 +445,53 @@ enum aco_option_type {
         * {endcode}
         */
        OPT_UINT_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.
+        *
+        * 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:
+        * {code}
+        * 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));
+        * {endcode}
+        */
+       OPT_YESNO_T,
+
+       /*! \brief 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.
+        *
+        * \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 {
+        *     int timelen;
+        * };
+        * {code}
+        * 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);
+        * {endcode}
+        */
+       OPT_TIMELEN_T,
+
 };
 
 /*! \brief A callback function for handling a particular option
@@ -461,7 +518,7 @@ enum aco_process_status {
 /*! \brief Process a config info via the options registered with an aco_info
  *
  * \param info The config_options_info to be used for handling the config
- * \param reload Whether or not this is a reload
+ * \param reload Non-zero if this is for a reload.
  *
  * \retval ACO_PROCESS_OK Success
  * \retval ACO_PROCESS_ERROR Failure
@@ -528,6 +585,7 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
  * \param type The option type (only for default handlers)
  * \param handler The handler function for the option (only for non-default types)
  * \param flags a type specific flags, stored in the option and available to the handler
+ * \param no_doc if non-zero, this option should not have documentation
  * \param argc The number for variadic arguments
  * \param ... field offsets to store for default handlers
  *
@@ -535,7 +593,7 @@ int aco_set_defaults(struct aco_type *type, const char *category, void *obj);
  * \retval -1 failure
  */
 int __aco_option_register(struct aco_info *info, const char *name, enum aco_matchtype match_type, struct aco_type **types,
-       const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, size_t argc, ...);
+       const char *default_val, enum aco_option_type type, aco_option_handler handler, unsigned int flags, unsigned int no_doc, size_t argc, ...);
 
 /*! \brief Register a config option
  * \param info A pointer to the aco_info struct
@@ -551,7 +609,7 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
  * \retval -1 Failure
  */
 #define aco_option_register(info, name, matchtype, types, default_val, opt_type, flags, ...) \
-       __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
+       __aco_option_register(info, name, matchtype, types, default_val, opt_type, NULL, flags, 0, VA_NARGS(__VA_ARGS__), __VA_ARGS__);
 
 /*! \brief Register a config option
  * \param info A pointer to the aco_info struct
@@ -566,7 +624,25 @@ int __aco_option_register(struct aco_info *info, const char *name, enum aco_matc
  * \retval -1 Failure
  */
 #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);
+       __aco_option_register(info, name, matchtype, types, default_val, OPT_CUSTOM_T, handler, flags, 0, 0);
+
+/*! \brief Register a config option with no expected documentation
+ * \param info A pointer to the aco_info struct
+ * \param name The name of the option
+ * \param matchtype
+ * \param types An array of valid option types for matching categories to the correct struct type
+ * \param default_val The default value of the option in the same format as defined in a config file
+ * \param handler The handler callback for the option
+ * \param flags \a type specific flags, stored in the option and available to the handler
+ *
+ * \note This is used primarily with custom options that only have internal purposes
+ * and that should be ignored by the user.
+ *
+ * \retval 0 Success
+ * \retval -1 Failure
+ */
+#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);
 
 /*! \brief Register a deprecated (and aliased) config option
  * \param info A pointer to the aco_info struct
@@ -589,6 +665,16 @@ int aco_option_register_deprecated(struct aco_info *info, const char *name, stru
  */
 unsigned int aco_option_get_flags(const struct aco_option *option);
 
+/*!
+ * \brief Get the offset position for an argument within a config option
+ *
+ * \param option Pointer to the aco_option struct
+ * \param arg Argument number
+ *
+ * \retval position of the argument
+ */
+intptr_t aco_option_get_argument(const struct aco_option *option, unsigned int position);
+
 /*! \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