[svn-commits] rmudgett: trunk r273197 - /trunk/include/asterisk/config.h
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Wed Jun 30 12:15:50 CDT 2010
Author: rmudgett
Date: Wed Jun 30 12:15:46 2010
New Revision: 273197
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=273197
Log:
Misc doxygen cleanup in config.h
Modified:
trunk/include/asterisk/config.h
Modified: trunk/include/asterisk/config.h
URL: http://svnview.digium.com/svn/asterisk/trunk/include/asterisk/config.h?view=diff&rev=273197&r1=273196&r2=273197
==============================================================================
--- trunk/include/asterisk/config.h (original)
+++ trunk/include/asterisk/config.h Wed Jun 30 12:15:46 2010
@@ -69,8 +69,7 @@
RQ_DATETIME,
} require_type;
-/*! \brief Structure for variables, used for configurations and for channel variables
-*/
+/*! \brief Structure for variables, used for configurations and for channel variables */
struct ast_variable {
const char *name;
const char *value;
@@ -122,41 +121,76 @@
struct ast_config_engine *next;
};
-/*! \brief Load a config file
- * \param filename path of file to open. If no preceding '/' character, path is considered relative to AST_CONFIG_DIR
- * Create a config structure from a given configuration file.
+/*!
+ * \brief Load a config file
+ *
+ * \param filename path of file to open. If no preceding '/' character,
+ * path is considered relative to AST_CONFIG_DIR
* \param who_asked The module which is making this request.
* \param flags Optional flags:
* CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
* CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
* CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
*
+ * \details
+ * Create a config structure from a given configuration file.
+ *
* \return an ast_config data structure on success
* \retval NULL on error
*/
struct ast_config *ast_config_load2(const char *filename, const char *who_asked, struct ast_flags flags);
+/*!
+ * \brief Load a config file
+ *
+ * \param filename path of file to open. If no preceding '/' character,
+ * path is considered relative to AST_CONFIG_DIR
+ * \param flags Optional flags:
+ * CONFIG_FLAG_WITHCOMMENTS - load the file with comments intact;
+ * CONFIG_FLAG_FILEUNCHANGED - check the file mtime and return CONFIG_STATUS_FILEUNCHANGED if the mtime is the same; or
+ * CONFIG_FLAG_NOCACHE - don't cache file mtime (main purpose of this option is to save memory on temporary files).
+ *
+ * \details
+ * Create a config structure from a given configuration file.
+ *
+ * \return an ast_config data structure on success
+ * \retval NULL on error
+ */
#define ast_config_load(filename, flags) ast_config_load2(filename, AST_MODULE, flags)
-/*! \brief Destroys a config
+/*!
+ * \brief Destroys a config
+ *
* \param config pointer to config data structure
+ *
+ * \details
* Free memory associated with a given config
- *
*/
void ast_config_destroy(struct ast_config *config);
-/*! \brief returns the root ast_variable of a config
+/*!
+ * \brief returns the root ast_variable of a config
+ *
* \param config pointer to an ast_config data structure
* \param cat name of the category for which you want the root
*
- * Returns the category specified
+ * \return the category specified
*/
struct ast_variable *ast_category_root(struct ast_config *config, char *cat);
-/*! \brief Goes through categories
+/*!
+ * \brief Goes through categories
+ *
* \param config Which config structure you wish to "browse"
* \param prev A pointer to a previous category.
- * This function is kind of non-intuitive in it's use. To begin, one passes NULL as the second argument. It will return a pointer to the string of the first category in the file. From here on after, one must then pass the previous usage's return value as the second pointer, and it will return a pointer to the category name afterwards.
+ *
+ * \details
+ * This function is kind of non-intuitive in it's use.
+ * To begin, one passes NULL as the second argument.
+ * It will return a pointer to the string of the first category in the file.
+ * From here on after, one must then pass the previous usage's return value
+ * as the second pointer, and it will return a pointer to the category name
+ * afterwards.
*
* \retval a category on success
* \retval NULL on failure/no-more-categories
@@ -165,6 +199,8 @@
/*!
* \brief Goes through variables
+ *
+ * \details
* Somewhat similar in intent as the ast_category_browse.
* List variables of config file category
*
@@ -175,6 +211,8 @@
/*!
* \brief given a pointer to a category, return the root variable.
+ *
+ * \details
* This is equivalent to ast_variable_browse(), but more efficient if we
* already have the struct ast_category * (e.g. from ast_category_get())
*/
@@ -182,9 +220,12 @@
/*!
* \brief Gets a variable
+ *
* \param config which (opened) config to use
* \param category category under which the variable lies
* \param variable which variable you wish to get the data for
+ *
+ * \details
* Goes through a given config file in the given category and searches for the given variable
*
* \retval The variable value on success
@@ -194,8 +235,11 @@
/*!
* \brief Retrieve a category if it exists
+ *
* \param config which config to use
* \param category_name name of the category you're looking for
+ *
+ * \details
* This will search through the categories within a given config file for a match.
*
* \retval pointer to category if found
@@ -205,8 +249,11 @@
/*!
* \brief Check for category duplicates
+ *
* \param config which config to use
* \param category_name name of the category you're looking for
+ *
+ * \details
* This will search through the categories within a given config file for a match.
*
* \return non-zero if found
@@ -215,16 +262,23 @@
/*!
* \brief Retrieve realtime configuration
+ *
* \param family which family/config to lookup
+ *
+ * \details
* This will use builtin configuration backends to look up a particular
- * entity in realtime and return a variable list of its parameters. Note
- * that unlike the variables in ast_config, the resulting list of variables
+ * entity in realtime and return a variable list of its parameters.
+ *
+ * \note
+ * Unlike the variables in ast_config, the resulting list of variables
* MUST be freed with ast_variables_destroy() as there is no container.
*
+ * \note
* The difference between these two calls is that ast_load_realtime excludes
* fields whose values are NULL, while ast_load_realtime_all loads all columns.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note
+ * You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
struct ast_variable *ast_load_realtime(const char *family, ...) attribute_sentinel;
@@ -232,18 +286,26 @@
/*!
* \brief Release any resources cached for a realtime family
+ * \since 1.6.1
+ *
* \param family which family/config to destroy
+ *
+ * \details
* Various backends may cache attributes about a realtime data storage
* facility; on reload, a front end resource may request to purge that cache.
+ *
* \retval 0 If any cache was purged
* \retval -1 If no cache was found
+ */
+int ast_unload_realtime(const char *family);
+
+/*!
+ * \brief Inform realtime what fields that may be stored
* \since 1.6.1
- */
-int ast_unload_realtime(const char *family);
-
-/*!
- * \brief Inform realtime what fields that may be stored
+ *
* \param family which family/config is referenced
+ *
+ * \details
* This will inform builtin configuration backends that particular fields
* may be updated during the use of that configuration section. This is
* mainly to be used during startup routines, to ensure that various fields
@@ -268,79 +330,97 @@
* \retval 0 Required fields met specified standards
* \retval -1 One or more fields was missing or insufficient
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
- *
- * \since 1.6.1
*/
int ast_realtime_require_field(const char *family, ...) attribute_sentinel;
/*!
* \brief Retrieve realtime configuration
+ *
* \param family which family/config to lookup
*
+ * \details
* This will use builtin configuration backends to look up a particular
* entity in realtime and return a variable list of its parameters. Unlike
* the ast_load_realtime, this function can return more than one entry and
* is thus stored inside a traditional ast_config structure rather than
* just returning a linked list of variables.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
struct ast_config *ast_load_realtime_multientry(const char *family, ...) attribute_sentinel;
/*!
* \brief Update realtime configuration
+ *
* \param family which family/config to be updated
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
+ *
+ * \details
* This function is used to update a parameter in realtime configuration space.
+ *
* \return Number of rows affected, or -1 on error.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
int ast_update_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
/*!
* \brief Update realtime configuration
+ *
* \param family which family/config to be updated
+ *
+ * \details
* This function is used to update a parameter in realtime configuration space.
* It includes the ability to lookup a row based upon multiple key criteria.
* As a result, this function includes two sentinel values, one to terminate
* lookup values and the other to terminate the listing of fields to update.
+ *
* \return Number of rows affected, or -1 on error.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
int ast_update2_realtime(const char *family, ...) attribute_sentinel;
/*!
* \brief Create realtime configuration
+ *
* \param family which family/config to be created
+ *
+ * \details
* This function is used to create a parameter in realtime configuration space.
+ *
* \return Number of rows affected, or -1 on error.
+ *
+ * \note
* On the MySQL engine only, for reasons of backwards compatibility, the return
* value is the insert ID. This value is nonportable and may be changed in a
* future version to match the other engines.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
int ast_store_realtime(const char *family, ...) attribute_sentinel;
/*!
* \brief Destroy realtime configuration
+ *
* \param family which family/config to be destroyed
* \param keyfield which field to use as the key
* \param lookup which value to look for in the key field to match the entry.
+ *
+ * \details
* This function is used to destroy an entry in realtime configuration space.
* Additional params are used as keys.
+ *
* \return Number of rows affected, or -1 on error.
*
- * Note that you should use the constant SENTINEL to terminate arguments, in
+ * \note You should use the constant SENTINEL to terminate arguments, in
* order to preserve cross-platform compatibility.
*/
int ast_destroy_realtime(const char *family, const char *keyfield, const char *lookup, ...) attribute_sentinel;
@@ -349,77 +429,102 @@
* \brief Check if realtime engine is configured for family
* \param family which family/config to be checked
* \return 1 if family is configured in realtime and engine exists
-*/
+ */
int ast_check_realtime(const char *family);
/*! \brief Check if there's any realtime engines loaded */
int ast_realtime_enabled(void);
-/*! \brief Free variable list
+/*!
+ * \brief Free variable list
* \param var the linked list of variables to free
+ *
+ * \details
* This function frees a list of variables.
*/
void ast_variables_destroy(struct ast_variable *var);
-/*! \brief Register config engine
+/*!
+ * \brief Register config engine
* \retval 1 Always
*/
int ast_config_engine_register(struct ast_config_engine *newconfig);
-/*! \brief Deregister config engine
+/*!
+ * \brief Deregister config engine
* \retval 0 Always
*/
int ast_config_engine_deregister(struct ast_config_engine *del);
-/*!\brief Exposed initialization method for core process
+/*!
+ * \brief Exposed initialization method for core process
+ *
+ * \details
* This method is intended for use only with the core initialization and is
* not designed to be called from any user applications.
*/
int register_config_cli(void);
-/*!\brief Exposed re-initialization method for core process
+/*!
+ * \brief Exposed re-initialization method for core process
+ *
+ * \details
* This method is intended for use only with the core re-initialization and is
* not designed to be called from any user applications.
*/
int read_config_maps(void);
-/*!\brief Create a new base configuration structure */
+/*! \brief Create a new base configuration structure */
struct ast_config *ast_config_new(void);
-/*!\brief Retrieve the current category name being built.
+/*!
+ * \brief Retrieve the current category name being built.
+ *
+ * \details
* API for backend configuration engines while building a configuration set.
*/
struct ast_category *ast_config_get_current_category(const struct ast_config *cfg);
-/*!\brief Set the category within the configuration as being current.
+/*!
+ * \brief Set the category within the configuration as being current.
+ *
+ * \details
* API for backend configuration engines while building a configuration set.
*/
void ast_config_set_current_category(struct ast_config *cfg, const struct ast_category *cat);
-/*!\brief Retrieve a configuration variable within the configuration set.
+/*!
+ * \brief Retrieve a configuration variable within the configuration set.
+ *
+ * \details
* Retrieves the named variable \p var within category \p cat of configuration
* set \p cfg. If not found, attempts to retrieve the named variable \p var
* from within category \em general.
+ *
* \return Value of \p var, or NULL if not found.
*/
const char *ast_config_option(struct ast_config *cfg, const char *cat, const char *var);
-/*!\brief Create a category structure */
+/*! \brief Create a category structure */
struct ast_category *ast_category_new(const char *name, const char *in_file, int lineno);
void ast_category_append(struct ast_config *config, struct ast_category *cat);
/*!
* \brief Inserts new category
+ *
* \param config which config to use
* \param cat newly created category to insert
* \param match which category to insert above
+ *
+ * \details
* This function is used to insert a new category above another category
* matching the match parameter.
*/
void ast_category_insert(struct ast_config *config, struct ast_category *cat, const char *match);
int ast_category_delete(struct ast_config *cfg, const char *category);
-/*!\brief Removes and destroys all variables within a category
+/*!
+ * \brief Removes and destroys all variables within a category
* \retval 0 if the category was found and emptied
* \retval -1 if the category was not found
*/
@@ -441,12 +546,15 @@
void ast_variable_insert(struct ast_category *category, struct ast_variable *variable, const char *line);
int ast_variable_delete(struct ast_category *category, const char *variable, const char *match, const char *line);
-/*! \brief Update variable value within a config
+/*!
+ * \brief Update variable value within a config
+ *
* \param category Category element within the config
* \param variable Name of the variable to change
* \param value New value of the variable
* \param match If set, previous value of the variable (if NULL or zero-length, no matching will be done)
* \param object Boolean of whether to make the new variable an object
+ *
* \return 0 on success or -1 on failure.
*/
int ast_variable_update(struct ast_category *category, const char *variable,
@@ -457,8 +565,10 @@
struct ast_config *ast_config_internal_load(const char *configfile, struct ast_config *cfg, struct ast_flags flags, const char *suggested_incl_file, const char *who_asked);
-/*! \brief Support code to parse config file arguments
- *
+/*!
+ * \brief Support code to parse config file arguments
+ *
+ * \details
* The function ast_parse_arg() provides a generic interface to parse
* strings (e.g. numbers, network addresses and so on) in a flexible
* way, e.g. by doing proper error and bound checks, provide default
@@ -466,8 +576,8 @@
* The function (described later) takes a string as an argument,
* a set of flags to specify the result format and checks to perform,
* a pointer to the result, and optionally some additional arguments.
- * It returns 0 on success, != 0 otherwise.
- *
+ *
+ * \return It returns 0 on success, != 0 otherwise.
*/
enum ast_parse_flags {
/* low 4 bits of flags are used for the operand type */
@@ -513,13 +623,16 @@
PARSE_PORT_FORBID = 0x0300, /* 0x100: forbid port number */
};
-/*! \brief The argument parsing routine.
+/*!
+ * \brief The argument parsing routine.
+ *
* \param arg the string to parse. It is not modified.
* \param flags combination of ast_parse_flags to specify the
* return type and additional checks.
* \param result pointer to the result. NULL is valid here, and can
* be used to perform only the validity checks.
* \param ... extra arguments are required according to flags.
+ *
* \retval 0 in case of success, != 0 otherwise.
* \retval result returns the parsed value in case of success,
* the default value in case of error, or it is left unchanged
@@ -527,6 +640,7 @@
* cases (e.g. sockaddr_in, with multi-field return values) some
* of the fields in result may be changed even if an error occurs.
*
+ * \details
* Examples of use:
* ast_parse_arg("223", PARSE_INT32|PARSE_IN_RANGE,
* &a, -1000, 1000);
@@ -575,7 +689,8 @@
/*! \brief call a generic function if the name matches. */
#define CV_F(__pattern, __body) if (!strcasecmp((__var), __pattern)) { __body; break; }
-/*! \brief helper macros to assign the value to a BOOL, UINT, static string and
+/*!
+ * \brief helper macros to assign the value to a BOOL, UINT, static string and
* dynamic string
*/
#define CV_BOOL(__x, __dst) CV_F(__x, (__dst) = ast_true(__val) )
@@ -584,7 +699,7 @@
#define CV_DSTR(__x, __dst) CV_F(__x, if (__dst) ast_free(__dst); __dst = ast_strdup(__val))
#define CV_STRFIELD(__x, __obj, __field) CV_F(__x, ast_string_field_set(__obj, __field, __val))
-/*!\brief Check if require type is an integer type */
+/*! \brief Check if require type is an integer type */
AST_INLINE_API(
int ast_rq_is_int(require_type type),
{
More information about the svn-commits
mailing list