[asterisk-commits] russell: trunk r76559 - in /trunk: channels/ include/ include/asterisk/ main/...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Mon Jul 23 09:32:05 CDT 2007
Author: russell
Date: Mon Jul 23 09:32:04 2007
New Revision: 76559
URL: http://svn.digium.com/view/asterisk?view=rev&rev=76559
Log:
(closes issue #10271)
Reported by: snuffy
Patches:
doxygen-updates.diff uploaded by snuffy (license 35)
Another big batch of doxygen documentation updates
Modified:
trunk/channels/chan_sip.c
trunk/include/asterisk.h
trunk/include/asterisk/doxyref.h
trunk/include/asterisk/file.h
trunk/include/jitterbuf.h
trunk/main/asterisk.c
trunk/main/devicestate.c
trunk/main/enum.c
trunk/res/res_clioriginate.c
trunk/res/res_config_odbc.c
trunk/res/res_config_sqlite.c
trunk/res/res_convert.c
trunk/res/res_crypto.c
trunk/res/res_indications.c
trunk/res/res_monitor.c
trunk/res/res_snmp.c
Modified: trunk/channels/chan_sip.c
URL: http://svn.digium.com/view/asterisk/trunk/channels/chan_sip.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/channels/chan_sip.c (original)
+++ trunk/channels/chan_sip.c Mon Jul 23 09:32:04 2007
@@ -13514,7 +13514,7 @@
if (p->owner)
ast_queue_control(p->owner, AST_CONTROL_BUSY);
break;
- case 482: /*
+ case 482: /*!
\note SIP is incapable of performing a hairpin call, which
is yet another failure of not having a layer 2 (again, YAY
IETF for thinking ahead). So we treat this as a call
Modified: trunk/include/asterisk.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk.h?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/include/asterisk.h (original)
+++ trunk/include/asterisk.h Mon Jul 23 09:32:04 2007
@@ -105,9 +105,10 @@
* \note Modules are reloaded using their reload() functions, not unloading
* them and loading them again.
*
- * \return Zero if the specified module was not found, 1 if the module was
- * found but cannot be reloaded, -1 if a reload operation is already in
- * progress, and 2 if the specfied module was found and reloaded.
+ * \return 0 if the specified module was not found.
+ * \retval 1 if the module was found but cannot be reloaded.
+ * \retval -1 if a reload operation is already in progress.
+ * \retval 2 if the specfied module was found and reloaded.
*/
int ast_module_reload(const char *name);
@@ -115,7 +116,8 @@
* \brief Register a function to be executed before Asterisk exits.
* \param func The callback function to use.
*
- * \return Zero on success, -1 on error.
+ * \retval 0 on success.
+ * \retval -1 on error.
*/
int ast_register_atexit(void (*func)(void));
Modified: trunk/include/asterisk/doxyref.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/doxyref.h?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/include/asterisk/doxyref.h (original)
+++ trunk/include/asterisk/doxyref.h Mon Jul 23 09:32:04 2007
@@ -551,4 +551,3 @@
* \arg \link Config_ami Configuration file \endlink
* \verbinclude ajam.txt
*/
-
Modified: trunk/include/asterisk/file.h
URL: http://svn.digium.com/view/asterisk/trunk/include/asterisk/file.h?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/include/asterisk/file.h (original)
+++ trunk/include/asterisk/file.h Mon Jul 23 09:32:04 2007
@@ -107,7 +107,7 @@
* When allocating a buffer, remember to leave AST_FRIENDLY_OFFSET
* spare bytes at the bginning.
*/
- int buf_size; /* size of frame buffer, if any, aligned to 8 bytes. */
+ int buf_size; /*!< size of frame buffer, if any, aligned to 8 bytes. */
int desc_size; /*!< size of private descriptor, if any */
struct ast_module *module;
@@ -134,9 +134,9 @@
int lasttimeout;
struct ast_channel *owner;
FILE *f;
- struct ast_frame fr; /* frame produced by read, typically */
- char *buf; /* buffer pointed to by ast_frame; */
- void *private; /* pointer to private buffer */
+ struct ast_frame fr; /*!< frame produced by read, typically */
+ char *buf; /*!< buffer pointed to by ast_frame; */
+ void *private; /*!< pointer to private buffer */
};
#define SEEK_FORCECUR 10
Modified: trunk/include/jitterbuf.h
URL: http://svn.digium.com/view/asterisk/trunk/include/jitterbuf.h?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/include/jitterbuf.h (original)
+++ trunk/include/jitterbuf.h Mon Jul 23 09:32:04 2007
@@ -21,18 +21,18 @@
#endif
/* configuration constants */
- /* Number of historical timestamps to use in calculating jitter and drift */
+ /*! Number of historical timestamps to use in calculating jitter and drift */
#define JB_HISTORY_SZ 500
- /* what percentage of timestamps should we drop from the history when we examine it;
+ /*! what percentage of timestamps should we drop from the history when we examine it;
* this might eventually be something made configurable */
#define JB_HISTORY_DROPPCT 3
- /* the maximum droppct we can handle (say it was configurable). */
+ /*! the maximum droppct we can handle (say it was configurable). */
#define JB_HISTORY_DROPPCT_MAX 4
- /* the size of the buffer we use to keep the top and botton timestamps for dropping */
+ /*! the size of the buffer we use to keep the top and botton timestamps for dropping */
#define JB_HISTORY_MAXBUF_SZ JB_HISTORY_SZ * JB_HISTORY_DROPPCT_MAX / 100
- /* amount of additional jitterbuffer adjustment */
+ /*! amount of additional jitterbuffer adjustment */
#define JB_TARGET_EXTRA 40
- /* ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
+ /*! ms between growing and shrinking; may not be honored if jitterbuffer runs out of space */
#define JB_ADJUST_DELAY 40
enum jb_return_code {
@@ -55,36 +55,36 @@
typedef struct jb_conf {
/* settings */
- long max_jitterbuf; /* defines a hard clamp to use in setting the jitter buffer delay */
- long resync_threshold; /* the jb will resync when delay increases to (2 * jitter) + this param */
- long max_contig_interp; /* the max interp frames to return in a row */
- long target_extra ; /* amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
+ long max_jitterbuf; /*!< defines a hard clamp to use in setting the jitter buffer delay */
+ long resync_threshold; /*!< the jb will resync when delay increases to (2 * jitter) + this param */
+ long max_contig_interp; /*!< the max interp frames to return in a row */
+ long target_extra ; /*!< amount of additional jitterbuffer adjustment, overrides JB_TARGET_EXTRA */
} jb_conf;
typedef struct jb_info {
jb_conf conf;
/* statistics */
- long frames_in; /* number of frames input to the jitterbuffer.*/
- long frames_out; /* number of frames output from the jitterbuffer.*/
- long frames_late; /* number of frames which were too late, and dropped.*/
- long frames_lost; /* number of missing frames.*/
- long frames_dropped; /* number of frames dropped (shrinkage) */
- long frames_ooo; /* number of frames received out-of-order */
- long frames_cur; /* number of frames presently in jb, awaiting delivery.*/
- long jitter; /* jitter measured within current history interval*/
- long min; /* minimum lateness within current history interval */
- long current; /* the present jitterbuffer adjustment */
- long target; /* the target jitterbuffer adjustment */
- long losspct; /* recent lost frame percentage (* 1000) */
- long next_voice_ts; /* the ts of the next frame to be read from the jb - in receiver's time */
- long last_voice_ms; /* the duration of the last voice frame */
- long silence_begin_ts; /* the time of the last CNG frame, when in silence */
- long last_adjustment; /* the time of the last adjustment */
- long last_delay; /* the last now added to history */
- long cnt_delay_discont; /* the count of discontinuous delays */
- long resync_offset; /* the amount to offset ts to support resyncs */
- long cnt_contig_interp; /* the number of contiguous interp frames returned */
+ long frames_in; /*!< number of frames input to the jitterbuffer.*/
+ long frames_out; /*!< number of frames output from the jitterbuffer.*/
+ long frames_late; /*!< number of frames which were too late, and dropped.*/
+ long frames_lost; /*!< number of missing frames.*/
+ long frames_dropped; /*!< number of frames dropped (shrinkage) */
+ long frames_ooo; /*!< number of frames received out-of-order */
+ long frames_cur; /*!< number of frames presently in jb, awaiting delivery.*/
+ long jitter; /*!< jitter measured within current history interval*/
+ long min; /*!< minimum lateness within current history interval */
+ long current; /*!< the present jitterbuffer adjustment */
+ long target; /*!< the target jitterbuffer adjustment */
+ long losspct; /*!< recent lost frame percentage (* 1000) */
+ long next_voice_ts; /*!< the ts of the next frame to be read from the jb - in receiver's time */
+ long last_voice_ms; /*!< the duration of the last voice frame */
+ long silence_begin_ts; /*!< the time of the last CNG frame, when in silence */
+ long last_adjustment; /*!< the time of the last adjustment */
+ long last_delay; /*!< the last now added to history */
+ long cnt_delay_discont; /*!< the count of discontinuous delays */
+ long resync_offset; /*!< the amount to offset ts to support resyncs */
+ long cnt_contig_interp; /*!< the number of contiguous interp frames returned */
} jb_info;
typedef struct jb_frame {
@@ -99,15 +99,15 @@
jb_info info;
/* history */
- long history[JB_HISTORY_SZ]; /* history */
- int hist_ptr; /* points to index in history for next entry */
- long hist_maxbuf[JB_HISTORY_MAXBUF_SZ]; /* a sorted buffer of the max delays (highest first) */
- long hist_minbuf[JB_HISTORY_MAXBUF_SZ]; /* a sorted buffer of the min delays (lowest first) */
- int hist_maxbuf_valid; /* are the "maxbuf"/minbuf valid? */
- unsigned int dropem:1; /* flag to indicate dropping frames (overload) */
+ long history[JB_HISTORY_SZ]; /*!< history */
+ int hist_ptr; /*!< points to index in history for next entry */
+ long hist_maxbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the max delays (highest first) */
+ long hist_minbuf[JB_HISTORY_MAXBUF_SZ]; /*!< a sorted buffer of the min delays (lowest first) */
+ int hist_maxbuf_valid; /*!< are the "maxbuf"/minbuf valid? */
+ unsigned int dropem:1; /*!< flag to indicate dropping frames (overload) */
- jb_frame *frames; /* queued frames */
- jb_frame *free; /* free frames (avoid malloc?) */
+ jb_frame *frames; /*!< queued frames */
+ jb_frame *free; /*!< free frames (avoid malloc?) */
} jitterbuf;
@@ -146,10 +146,10 @@
* This value may change as frames are added (esp non-audio frames) */
long jb_next(jitterbuf *jb);
-/* get jitterbuf info: only "statistics" may be valid */
+/*! get jitterbuf info: only "statistics" may be valid */
enum jb_return_code jb_getinfo(jitterbuf *jb, jb_info *stats);
-/* set jitterbuf conf */
+/*! set jitterbuf conf */
enum jb_return_code jb_setconf(jitterbuf *jb, jb_conf *conf);
typedef void (*jb_output_function_t)(const char *fmt, ...);
Modified: trunk/main/asterisk.c
URL: http://svn.digium.com/view/asterisk/trunk/main/asterisk.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/main/asterisk.c (original)
+++ trunk/main/asterisk.c Mon Jul 23 09:32:04 2007
@@ -153,9 +153,9 @@
"production installations.\n");
/*! \defgroup main_options Main Configuration Options
- \brief Main configuration options from \ref Config_ast "asterisk.conf" or
- the operating system command line when starting Asterisk
- Some of them can be changed in the CLI
+ * \brief Main configuration options from asterisk.conf or OS command line on starting Asterisk.
+ * \arg \ref Config_ast "asterisk.conf"
+ * \note Some of them can be changed in the CLI
*/
/*! @{ */
Modified: trunk/main/devicestate.c
URL: http://svn.digium.com/view/asterisk/trunk/main/devicestate.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/main/devicestate.c (original)
+++ trunk/main/devicestate.c Mon Jul 23 09:32:04 2007
@@ -93,7 +93,7 @@
* and reported back.
*
* - Extension states
- * \arg \ref ENUM ast_extension_states
+ * \arg \ref AstENUM ast_extension_states
* \arg \ref pbx.c
* \arg \ref pbx.h
* - Structures
Modified: trunk/main/enum.c
URL: http://svn.digium.com/view/asterisk/trunk/main/enum.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/main/enum.c (original)
+++ trunk/main/enum.c Mon Jul 23 09:32:04 2007
@@ -362,7 +362,7 @@
return 0;
}
-/*! \brief ENUM lookup */
+/* ENUM lookup */
int ast_get_enum(struct ast_channel *chan, const char *number, char *dst, int dstlen, char *tech, int techlen, char* suffix, char* options, unsigned int record, struct enum_context **argcontext)
{
struct enum_context *context;
@@ -532,9 +532,7 @@
return ret;
}
-/*! \brief Get TXT record from DNS.
- Really has nothing to do with enum, but anyway...
- */
+/* Get TXT record from DNS. Really has nothing to do with enum, but anyway... */
int ast_get_txt(struct ast_channel *chan, const char *number, char *dst, int dstlen, char *tech, int techlen, char *txt, int txtlen)
{
struct enum_context context;
Modified: trunk/res/res_clioriginate.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_clioriginate.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_clioriginate.c (original)
+++ trunk/res/res_clioriginate.c Mon Jul 23 09:32:04 2007
@@ -69,6 +69,15 @@
orig_help, complete_orig },
};
+/*!
+ * \brief orginate a call from the CLI
+ * \param fd file descriptor for cli
+ * \param chan channel to create type/data
+ * \param app application you want to run
+ * \param appdata data for application
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
static int orig_app(int fd, const char *chan, const char *app, const char *appdata)
{
char *chantech;
@@ -91,6 +100,14 @@
return RESULT_SUCCESS;
}
+/*!
+ * \brief orginate from extension
+ * \param fd file descriptor for cli
+ * \param chan channel to create type/data
+ * \param data contains exten\@context
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
static int orig_exten(int fd, const char *chan, const char *data)
{
char *chantech;
@@ -122,6 +139,14 @@
return RESULT_SUCCESS;
}
+/*!
+ * \brief handle for orgination app or exten.
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv contains either application or extension arguements
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
static int handle_orig(int fd, int argc, char *argv[])
{
int res;
@@ -144,6 +169,15 @@
return res;
}
+/*!
+ * \brief complete suggestions for orginate command
+ * \param line
+ * \param word to be completed word
+ * \param pos position
+ * \param state
+ * \retval completed word
+ * \retval NULL on failure
+*/
static char *complete_orig(const char *line, const char *word, int pos, int state)
{
static char *choices[] = { "application", "extension", NULL };
@@ -160,12 +194,14 @@
return ret;
}
+/*! \brief Unload orginate module */
static int unload_module(void)
{
ast_cli_unregister_multiple(cli_cliorig, sizeof(cli_cliorig) / sizeof(struct ast_cli_entry));
return 0;
}
+/*! \brief Load orginate module */
static int load_module(void)
{
ast_cli_register_multiple(cli_cliorig, sizeof(cli_cliorig) / sizeof(struct ast_cli_entry));
Modified: trunk/res/res_config_odbc.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_config_odbc.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_config_odbc.c (original)
+++ trunk/res/res_config_odbc.c Mon Jul 23 09:32:04 2007
@@ -54,6 +54,18 @@
#include "asterisk/res_odbc.h"
#include "asterisk/utils.h"
+/*!
+ * \brief Excute an SQL query and return ast_variable list
+ * \param database
+ * \param table
+ * \param ap list containing one or more field/operator/value set
+ * Select database and preform query on table, prepare the sql statement
+ * Sub-in the values to the prepared statement and execute it. Return results
+ * as a ast_variable list.
+ *
+ * \retval var on success
+ * \retval NULL on failure
+*/
static struct ast_variable *realtime_odbc(const char *database, const char *table, va_list ap)
{
struct odbc_obj *obj;
@@ -204,6 +216,19 @@
return var;
}
+/*!
+ * \brief Excute an Select query and return ast_config list
+ * \param database
+ * \param table
+ * \param ap list containing one or more field/operator/value set
+ * Select database and preform query on table, prepare the sql statement
+ * Sub-in the values to the prepared statement and execute it.
+ * Execute this prepared query against several ODBC connected databases.
+ * Return results as an ast_config variable.
+ *
+ * \retval var on success
+ * \retval NULL on failure
+*/
static struct ast_config *realtime_multi_odbc(const char *database, const char *table, va_list ap)
{
struct odbc_obj *obj;
@@ -360,6 +385,20 @@
return cfg;
}
+/*!
+ * \brief Excute an UPDATE query
+ * \param database
+ * \param table
+ * \param keyfield where clause field
+ * \param lookup value of field for where clause
+ * \param ap list containing one or more field/value set(s)
+ * Update a database table, prepare the sql statement using keyfield and lookup
+ * control the number of records to change. All values to be changed are stored in ap list.
+ * Sub-in the values to the prepared statement and execute it.
+ *
+ * \retval number of rows affected
+ * \retval -1 on failure
+*/
static int update_odbc(const char *database, const char *table, const char *keyfield, const char *lookup, va_list ap)
{
struct odbc_obj *obj;
Modified: trunk/res/res_config_sqlite.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_config_sqlite.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_config_sqlite.c (original)
+++ trunk/res/res_config_sqlite.c Mon Jul 23 09:32:04 2007
@@ -20,7 +20,7 @@
*/
/*!
- * \mainpage res_config_sqlite
+ * \page res_config_sqlite
*
* \section intro_sec Presentation
*
@@ -232,56 +232,58 @@
};
/*!
- * Allocate a variable.
- *
- * \param var the address of the variable to set (it will be allocated)
- * \param name the name of the variable (for error handling)
+ * \brief Allocate a variable.
+ * \param var the address of the variable to set (it will be allocated)
+ * \param name the name of the variable (for error handling)
* \param value the value to store in var
- * \return 1 if an allocation error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an allocation error occurred
*/
static int set_var(char **var, char *name, char *value);
/*!
- * Load the configuration file.
+ * \brief Load the configuration file.
+ * \see unload_config()
*
* This function sets dbfile, config_table, and cdr_table. It calls
* check_vars() before returning, and unload_config() if an error occurred.
*
- * \return 1 if an error occurred, 0 otherwise
- * \see unload_config()
+ * \retval 0 on success
+ * \retval 1 if an error occurred
*/
static int load_config(void);
/*!
- * Free resources related to configuration.
- *
+ * \brief Free resources related to configuration.
* \see load_config()
*/
static void unload_config(void);
/*!
- * Asterisk callback function for CDR support.
+ * \brief Asterisk callback function for CDR support.
+ * \param cdr the CDR entry Asterisk sends us
*
* Asterisk will call this function each time a CDR entry must be logged if
* CDR support is enabled.
*
- * \param cdr the CDR entry Asterisk sends us
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an error occurred
*/
static int cdr_handler(struct ast_cdr *cdr);
/*!
- * SQLite callback function for static configuration.
+ * \brief SQLite callback function for static configuration.
*
* This function is passed to the SQLite engine as a callback function to
* parse a row and store it in a struct ast_config object. It relies on
* resulting rows being sorted by category.
*
- * \param arg a pointer to a struct cfg_entry_args object
- * \param argc number of columns
- * \param argv values in the row
+ * \param arg a pointer to a struct cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
* \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success
+ * \retval 1 if an error occurred
* \see cfg_entry_args
* \see sql_get_config_table
* \see config_handler()
@@ -289,17 +291,18 @@
static int add_cfg_entry(void *arg, int argc, char **argv, char **columnNames);
/*!
- * Asterisk callback function for static configuration.
+ * \brief Asterisk callback function for static configuration.
*
* Asterisk will call this function when it loads its static configuration,
* which usually happens at startup and reload.
*
* \param database the database to use (ignored)
- * \param table the table to use
- * \param file the file to load from the database
- * \param cfg the struct ast_config object to use when storing variables
+ * \param table the table to use
+ * \param file the file to load from the database
+ * \param cfg the struct ast_config object to use when storing variables
* \param withcomments Integer. Flag
- * \return NULL if an error occurred, cfg otherwise
+ * \retval cfg object
+ * \retval NULL if an error occurred
* \see add_cfg_entry()
*/
static struct ast_config * config_handler(const char *database,
@@ -307,7 +310,7 @@
struct ast_config *cfg, int withcomments);
/*!
- * Helper function to parse a va_list object into 2 dynamic arrays of
+ * \brief Helper function to parse a va_list object into 2 dynamic arrays of
* strings, parameters and values.
*
* ap must have the following format : param1 val1 param2 val2 param3 val3 ...
@@ -322,26 +325,27 @@
* is the responsibility of the caller to release the memory of these arrays.
* It is considered an error that va_list has a null or odd number of strings.
*
- * \param ap the va_list object to parse
+ * \param ap the va_list object to parse
* \param params_ptr where the address of the params array is stored
- * \param vals_ptr where the address of the vals array is stored
- * \return 0 if an error occurred, the number of elements in the arrays (which
- * have the same size) otherwise
+ * \param vals_ptr where the address of the vals array is stored
+ * \retval the number of elements in the arrays (which have the same size).
+ * \retval 0 if an error occurred.
*/
static size_t get_params(va_list ap, const char ***params_ptr,
const char ***vals_ptr);
/*!
- * SQLite callback function for RealTime configuration.
+ * \brief SQLite callback function for RealTime configuration.
*
* This function is passed to the SQLite engine as a callback function to
* parse a row and store it in a linked list of struct ast_variable objects.
*
- * \param arg a pointer to a struct rt_cfg_entry_args object
- * \param argc number of columns
- * \param argv values in the row
+ * \param arg a pointer to a struct rt_cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
* \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success.
+ * \retval 1 if an error occurred.
* \see rt_cfg_entry_args
* \see realtime_handler()
*/
@@ -360,25 +364,27 @@
* \param database the database to use (ignored)
* \param table the table to use
* \param ap list of parameters and values to match
- * \return NULL if an error occurred, a linked list of struct ast_variable
- * objects otherwise
+ *
+ * \retval a linked list of struct ast_variable objects
+ * \retval NULL if an error occurred
* \see add_rt_cfg_entry()
*/
static struct ast_variable * realtime_handler(const char *database,
const char *table, va_list ap);
/*!
- * SQLite callback function for RealTime configuration.
+ * \brief SQLite callback function for RealTime configuration.
*
* This function performs the same actions as add_rt_cfg_entry() except
* that the rt_multi_cfg_entry_args structure is designed to store
* categories in addition of variables.
*
- * \param arg a pointer to a struct rt_multi_cfg_entry_args object
- * \param argc number of columns
- * \param argv values in the row
+ * \param arg a pointer to a struct rt_multi_cfg_entry_args object
+ * \param argc number of columns
+ * \param argv values in the row
* \param columnNames names and types of the columns
- * \return 1 if an error occurred, 0 otherwise
+ * \retval 0 on success.
+ * \retval 1 if an error occurred.
* \see rt_multi_cfg_entry_args
* \see realtime_multi_handler()
*/
@@ -386,17 +392,18 @@
char **columnNames);
/*!
- * Asterisk callback function for RealTime configuration.
+ * \brief Asterisk callback function for RealTime configuration.
*
* This function performs the same actions as realtime_handler() except
* that it can store variables per category, and can return several
* categories.
*
* \param database the database to use (ignored)
- * \param table the table to use
- * \param ap list of parameters and values to match
- * \return NULL if an error occurred, a struct ast_config object storing
- * categories and variables
+ * \param table the table to use
+ * \param ap list of parameters and values to match
+ * \retval a struct ast_config object storing categories and variables.
+ * \retval NULL if an error occurred.
+ *
* \see add_rt_multi_cfg_entry()
*/
static struct ast_config * realtime_multi_handler(const char *database,
@@ -404,7 +411,7 @@
va_list ap);
/*!
- * Asterisk callback function for RealTime configuration (variable
+ * \brief Asterisk callback function for RealTime configuration (variable
* update).
*
* Asterisk will call this function each time a variable has been modified
@@ -414,64 +421,49 @@
* same format as the other realtime functions.
*
* \param database the database to use (ignored)
- * \param table the table to use
+ * \param table the table to use
* \param keyfield the column of the matching cell
- * \param entity the value of the matching cell
- * \param ap list of parameters and new values to update in the database
- * \return -1 if an error occurred, the number of affected rows otherwise
+ * \param entity the value of the matching cell
+ * \param ap list of parameters and new values to update in the database
+ * \retval the number of affected rows.
+ * \retval -1 if an error occurred.
*/
static int realtime_update_handler(const char *database, const char *table,
const char *keyfield, const char *entity,
va_list ap);
/*!
- * Asterisk callback function for the CLI status command.
- *
- * \param fd file descriptor provided by Asterisk to use with ast_cli()
+ * \brief Asterisk callback function for the CLI status command.
+ *
+ * \param fd file descriptor provided by Asterisk to use with ast_cli()
* \param argc number of arguments
* \param argv arguments list
* \return RESULT_SUCCESS
*/
static int cli_status(int fd, int argc, char *argv[]);
-/*!
- * The SQLite database object.
- */
+/*! The SQLite database object. */
static sqlite *db;
-/*!
- * Set to 1 if CDR support is enabled.
- */
+/*! Set to 1 if CDR support is enabled. */
static int use_cdr;
-/*!
- * Set to 1 if the CDR callback function was registered.
- */
+/*! Set to 1 if the CDR callback function was registered. */
static int cdr_registered;
-/*!
- * Set to 1 if the CLI status command callback function was registered.
- */
+/*! Set to 1 if the CLI status command callback function was registered. */
static int cli_status_registered;
-/*!
- * The path of the database file.
- */
+/*! The path of the database file. */
static char *dbfile;
-/*!
- * The name of the static configuration table.
- */
+/*! The name of the static configuration table. */
static char *config_table;
-/*!
- * The name of the table used to store CDR entries.
- */
+/*! The name of the table used to store CDR entries. */
static char *cdr_table;
-/*!
- * The number of registered virtual machines.
- */
+/*! The number of registered virtual machines. */
static int vm_count;
/*!
@@ -509,9 +501,7 @@
* Taken from Asterisk 1.2 cdr_sqlite.so.
*/
-/*!
- * SQL query format to create the CDR table if non existent.
- */
+/*! SQL query format to create the CDR table if non existent. */
static char *sql_create_cdr_table =
"CREATE TABLE '%q' ("
" id INTEGER PRIMARY KEY,"
@@ -535,9 +525,7 @@
" userfield VARCHAR(255) NOT NULL DEFAULT ''"
");";
-/*!
- * SQL query format to insert a CDR entry.
- */
+/*! SQL query format to insert a CDR entry. */
static char *sql_add_cdr_entry =
"INSERT INTO '%q' ("
" clid,"
@@ -583,7 +571,7 @@
* SQL query format to fetch the static configuration of a file.
* Rows must be sorted by category.
*
- * @see add_cfg_entry()
+ * \see add_cfg_entry()
*/
static char *sql_get_config_table =
"SELECT *"
Modified: trunk/res/res_convert.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_convert.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_convert.c (original)
+++ trunk/res/res_convert.c Mon Jul 23 09:32:04 2007
@@ -56,7 +56,14 @@
return 0;
}
-/*! \brief Convert a file from one format to another */
+/*!
+ * \brief Convert a file from one format to another
+ * \param fd file descriptor
+ * \param argc no arguements
+ * \param argv list of arguements
+ * \retval RESULT_SUCCESS on success.
+ * \retval RESULT_SHOWUSAGE on failure.
+*/
static int cli_audio_convert(int fd, int argc, char *argv[])
{
int ret = RESULT_FAILURE;
Modified: trunk/res/res_crypto.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_crypto.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_crypto.c (original)
+++ trunk/res/res_crypto.c Mon Jul 23 09:32:04 2007
@@ -84,21 +84,21 @@
#define KEY_NEEDS_PASSCODE (1 << 16)
struct ast_key {
- /* Name of entity */
+ /*! Name of entity */
char name[80];
- /* File name */
+ /*! File name */
char fn[256];
- /* Key type (AST_KEY_PUB or AST_KEY_PRIV, along with flags from above) */
+ /*! Key type (AST_KEY_PUB or AST_KEY_PRIV, along with flags from above) */
int ktype;
- /* RSA structure (if successfully loaded) */
+ /*! RSA structure (if successfully loaded) */
RSA *rsa;
- /* Whether we should be deleted */
+ /*! Whether we should be deleted */
int delme;
- /* FD for input (or -1 if no input allowed, or -2 if we needed input) */
+ /*! FD for input (or -1 if no input allowed, or -2 if we needed input) */
int infd;
- /* FD for output */
+ /*! FD for output */
int outfd;
- /* Last MD5 Digest */
+ /*! Last MD5 Digest */
unsigned char digest[16];
struct ast_key *next;
};
@@ -112,6 +112,16 @@
return write(fd, s, strlen(s) + 1);
}
#endif
+
+
+/*!
+ * \brief setting of priv key
+ * \param buf
+ * \param size
+ * \param rwflag
+ * \param userdata
+ * \return length of string,-1 on failure
+*/
static int pw_cb(char *buf, int size, int rwflag, void *userdata)
{
struct ast_key *key = (struct ast_key *)userdata;
@@ -137,6 +147,10 @@
return -1;
}
+/*!
+ * \brief return the ast_key structure for name
+ * \see ast_key_get
+*/
static struct ast_key *__ast_key_get(const char *kname, int ktype)
{
struct ast_key *key;
@@ -152,6 +166,16 @@
return key;
}
+/*!
+ * \brief load RSA key from file
+ * \param dir directory string
+ * \param fname name of file
+ * \param ifd incoming file descriptor
+ * \param ofd outgoing file descriptor
+ * \param not2
+ * \retval key on success.
+ * \retval NULL on failure.
+*/
static struct ast_key *try_load_key (char *dir, char *fname, int ifd, int ofd, int *not2)
{
int ktype = 0;
@@ -318,6 +342,10 @@
#endif
+/*!
+ * \brief signs outgoing message with public key
+ * \see ast_sign_bin
+*/
static int __ast_sign_bin(struct ast_key *key, const char *msg, int msglen, unsigned char *dsig)
{
unsigned char digest[20];
@@ -349,6 +377,10 @@
}
+/*!
+ * \brief decrypt a message
+ * \see ast_decrypt_bin
+*/
static int __ast_decrypt_bin(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key)
{
int res;
@@ -375,6 +407,10 @@
return pos;
}
+/*!
+ * \brief encrypt a message
+ * \see ast_encrypt_bin
+*/
static int __ast_encrypt_bin(unsigned char *dst, const unsigned char *src, int srclen, struct ast_key *key)
{
int res;
@@ -403,6 +439,10 @@
return pos;
}
+/*!
+ * \brief wrapper for __ast_sign_bin then base64 encode it
+ * \see ast_sign
+*/
static int __ast_sign(struct ast_key *key, char *msg, char *sig)
{
unsigned char dsig[128];
@@ -416,6 +456,10 @@
}
+/*!
+ * \brief check signature of a message
+ * \see ast_check_signature_bin
+*/
static int __ast_check_signature_bin(struct ast_key *key, const char *msg, int msglen, const unsigned char *dsig)
{
unsigned char digest[20];
@@ -442,6 +486,10 @@
return 0;
}
+/*!
+ * \brief base64 decode then sent to __ast_check_signature_bin
+ * \see ast_check_signature
+*/
static int __ast_check_signature(struct ast_key *key, const char *msg, const char *sig)
{
unsigned char dsig[128];
@@ -457,6 +505,12 @@
return res;
}
+/*!
+ * \brief refresh RSA keys from file
+ * \param ifd file descriptor
+ * \param ofd file descriptor
+ * \return void
+*/
static void crypto_load(int ifd, int ofd)
{
struct ast_key *key, *nkey, *last;
@@ -512,6 +566,13 @@
sum += sprintf(sum, "%02x", *(md5++));
}
+/*!
+ * \brief show the list of RSA keys
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv list of arguements
+ * \return RESULT_SUCCESS
+*/
static int show_keys(int fd, int argc, char *argv[])
{
struct ast_key *key;
@@ -535,6 +596,13 @@
return RESULT_SUCCESS;
}
+/*!
+ * \brief initialize all RSA keys
+ * \param fd file descriptor
+ * \param argc no of arguements
+ * \param argv list of arguements
+ * \return RESULT_SUCCESS
+*/
static int init_keys(int fd, int argc, char *argv[])
{
struct ast_key *key;
@@ -573,6 +641,7 @@
init_keys_usage },
};
+/*! \brief initialise the res_crypto module */
static int crypto_init(void)
{
SSL_library_init();
Modified: trunk/res/res_indications.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_indications.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_indications.c (original)
+++ trunk/res/res_indications.c Mon Jul 23 09:32:04 2007
@@ -80,8 +80,11 @@
* Implementation of functions provided by this module
*/
-/*
- * ADD INDICATION command stuff
+/*!
+ * \brief Add a country to indication
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
*/
static int handle_add_indication(int fd, int argc, char *argv[])
{
@@ -114,8 +117,11 @@
return 0;
}
-/*
- * REMOVE INDICATION command stuff
+/*!
+ * \brief Remove a country from indication
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
*/
static int handle_remove_indication(int fd, int argc, char *argv[])
{
@@ -143,8 +149,11 @@
return 0;
}
-/*
- * SHOW INDICATIONS command stuff
+/*!
+ * \brief Show the current indications
+ * \param fd file descriptor of CLI
+ * \param argc no of args
+ * \param argv arguements
*/
static int handle_show_indications(int fd, int argc, char *argv[])
{
@@ -191,8 +200,10 @@
return -1;
}
-/*
- * Playtones command stuff
+/*!
+ * \brief play tone for indication country
+ * \param chan ast_channel to play the sounds back to
+ * \param data contains tone to play
*/
static int handle_playtones(struct ast_channel *chan, void *data)
{
@@ -213,8 +224,10 @@
return res;
}
-/*
- * StopPlaylist command stuff
+/*!
+ * \brief Stop tones playing
+ * \param chan
+ * \param data
*/
static int handle_stopplaytones(struct ast_channel *chan, void *data)
{
@@ -222,9 +235,7 @@
return 0;
}
-/*
- * Load module stuff
- */
+/*! \brief load indications module */
static int ind_load_module(void)
{
struct ast_config *cfg;
@@ -342,9 +353,7 @@
return 0;
}
-/*
- * CLI entries for commands provided by this module
- */
+/*! \brief CLI entries for commands provided by this module */
static struct ast_cli_entry cli_indications[] = {
{ { "indication", "add", NULL },
handle_add_indication, "Add the given indication to the country",
@@ -359,9 +368,7 @@
help_show_indications },
};
-/*
- * Standard module functions ...
- */
+/*! \brief Unload indicators module */
static int unload_module(void)
{
/* remove the registed indications... */
@@ -375,6 +382,7 @@
}
+/*! \brief Load indications module */
static int load_module(void)
{
if (ind_load_module())
@@ -386,6 +394,7 @@
return 0;
}
+/*! \brief Reload indications module */
static int reload(void)
{
/* remove the registed indications... */
Modified: trunk/res/res_monitor.c
URL: http://svn.digium.com/view/asterisk/trunk/res/res_monitor.c?view=diff&rev=76559&r1=76558&r2=76559
==============================================================================
--- trunk/res/res_monitor.c (original)
+++ trunk/res/res_monitor.c Mon Jul 23 09:32:04 2007
@@ -115,6 +115,13 @@
"Unpauses monitoring of a channel on which monitoring had\n"
"previously been paused with PauseMonitor.\n";
+/*!
+ * \brief Change state of monitored channel
+ * \param chan
+ * \param state monitor state
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
static int ast_monitor_set_state(struct ast_channel *chan, int state)
{
LOCK_IF_NEEDED(chan, 1);
@@ -133,7 +140,10 @@
* \param fname_base filename base to record to
* \param need_lock whether to lock the channel mutex
* \param stream_action whether to record the input and/or output streams. X_REC_IN | X_REC_OUT is most often used
- * \returns 0 on success, -1 on failure
+ * Creates the file to record, if no format is specified it assumes WAV
+ * It also sets channel variable __MONITORED=yes
+ * \retval 0 on success
+ * \retval -1 on failure
*/
int ast_monitor_start( struct ast_channel *chan, const char *format_spec,
const char *fname_base, int need_lock, int stream_action)
@@ -241,7 +251,9 @@
return res;
}
-/*
+/*!
+ * \brief Get audio format.
+ * \param format recording format.
* The file format extensions that Asterisk uses are not all the same as that
* which soxmix expects. This function ensures that the format used as the
* extension on the filename is something soxmix will understand.
@@ -258,7 +270,13 @@
return res;
}
-/* Stop monitoring a channel */
+/*!
+ * \brief Stop monitoring channel
+ * \param chan
+ * \param need_lock
+ * Stop the recording, close any open streams, mix in/out channels if required
+ * \return Always 0
+*/
int ast_monitor_stop(struct ast_channel *chan, int need_lock)
{
int delfiles = 0;
@@ -339,29 +357,38 @@
}
[... 109 lines stripped ...]
More information about the asterisk-commits
mailing list