(closes issue #10271)
authorRussell Bryant <russell@russellbryant.com>
Mon, 23 Jul 2007 14:32:04 +0000 (14:32 +0000)
committerRussell Bryant <russell@russellbryant.com>
Mon, 23 Jul 2007 14:32:04 +0000 (14:32 +0000)
Reported by: snuffy
Patches:
      doxygen-updates.diff uploaded by snuffy (license 35)

Another big batch of doxygen documentation updates

git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@76559 65c4cc65-6c06-0410-ace0-fbb531ad65f3

16 files changed:
channels/chan_sip.c
include/asterisk.h
include/asterisk/doxyref.h
include/asterisk/file.h
include/jitterbuf.h
main/asterisk.c
main/devicestate.c
main/enum.c
res/res_clioriginate.c
res/res_config_odbc.c
res/res_config_sqlite.c
res/res_convert.c
res/res_crypto.c
res/res_indications.c
res/res_monitor.c
res/res_snmp.c

index 90251ee..06613fc 100644 (file)
@@ -13514,7 +13514,7 @@ static void handle_response(struct sip_pvt *p, int resp, char *rest, struct sip_
                                        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
index 6e20c16..7dd5897 100644 (file)
@@ -105,9 +105,10 @@ struct ast_module;
  * \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 @@ int ast_module_reload(const char *name);
  * \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));
 
index 3d05118..bf538c6 100644 (file)
@@ -551,4 +551,3 @@ DUNDi is not itself a Voice-over IP signaling or media protocol. Instead, it pub
  *  \arg \link Config_ami Configuration file \endlink
  *  \verbinclude ajam.txt
  */
-
index 0087597..22a887c 100644 (file)
@@ -107,7 +107,7 @@ struct ast_format {
         * 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 @@ struct ast_filestream {
        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
index d2635f3..d2e5b5a 100644 (file)
@@ -21,18 +21,18 @@ extern "C" {
 #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 @@ enum jb_frame_type {
 
 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 @@ typedef struct jitterbuf {
        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) */
-
-       jb_frame *frames;               /* queued frames */
-       jb_frame *free;                 /* free frames (avoid malloc?) */
+       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?) */
 } jitterbuf;
 
 
@@ -146,10 +146,10 @@ enum jb_return_code jb_getall(jitterbuf *jb, jb_frame *frameout);
  * 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, ...);
index 7f99812..118dd29 100644 (file)
@@ -153,9 +153,9 @@ int daemon(int, int);  /* defined in libresolv of all places */
                 "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 
  */
 /*! @{ */
 
index a233e56..05a7752 100644 (file)
@@ -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
index 1c9d341..cf298a6 100644 (file)
@@ -362,7 +362,7 @@ static int enum_callback(void *context, unsigned char *answer, int len, unsigned
        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 @@ int ast_get_enum(struct ast_channel *chan, const char *number, char *dst, int ds
        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;
index 44afd7b..8497f63 100644 (file)
@@ -69,6 +69,15 @@ struct ast_cli_entry cli_cliorig[] = {
        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 @@ static int orig_app(int fd, const char *chan, const char *app, const char *appda
        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 @@ static int orig_exten(int fd, const char *chan, const char *data)
        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 @@ static int handle_orig(int fd, int argc, char *argv[])
        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 @@ static char *complete_orig(const char *line, const char *word, int pos, int stat
        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));
index 28c8c31..2c8b90e 100644 (file)
@@ -54,6 +54,18 @@ ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
 #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 @@ static struct ast_variable *realtime_odbc(const char *database, const char *tabl
        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 @@ static struct ast_config *realtime_multi_odbc(const char *database, const char *
        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;
index 9aa37d5..c9c65f8 100644 (file)
@@ -20,7 +20,7 @@
  */
 
 /*!
- * \mainpage res_config_sqlite
+ * \page res_config_sqlite
  * 
  * \section intro_sec Presentation
  * 
@@ -232,56 +232,58 @@ struct rt_multi_cfg_entry_args {
 };
 
 /*!
- * 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 cdr_handler(struct ast_cdr *cdr);
 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 @@ static struct ast_config * config_handler(const char *database,
        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 @@ static struct ast_config * config_handler(const char *database,
  * 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 @@ static int add_rt_cfg_entry(void *arg, int argc, char **argv,
  * \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 @@ static int add_rt_multi_cfg_entry(void *arg, int argc, char **argv,
        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 @@ static struct ast_config * realtime_multi_handler(const char *database,
        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 @@ static struct ast_config * realtime_multi_handler(const char *database,
  * 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.
+ * \brief Asterisk callback function for the CLI status command.
  * 
- * \param fd    file descriptor provided by Asterisk to use with ast_cli()
+ * \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 @@ static struct ast_cli_entry cli_status_cmd =
  * 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 @@ static char *sql_create_cdr_table =
 "      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 @@ static char *sql_add_cdr_entry =
  * 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 *"
index be3d177..34606ac 100644 (file)
@@ -56,7 +56,14 @@ static int split_ext(char *filename, char **name, char **ext)
        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;
index 73a54ba..1897ab1 100644 (file)
@@ -84,21 +84,21 @@ AST_MUTEX_DEFINE_STATIC(keylock);
 #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 @@ static int fdprint(int fd, char *s)
         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 @@ static int pw_cb(char *buf, int size, int rwflag, void *userdata)
        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 @@ static struct ast_key *__ast_key_get(const char *kname, int ktype)
        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 @@ static char *binary(int y, int len)
 
 #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 @@ static int __ast_sign_bin(struct ast_key *key, const char *msg, int msglen, unsi
        
 }
 
+/*!
+ * \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 @@ static int __ast_decrypt_bin(unsigned char *dst, const unsigned char *src, int s
        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 @@ static int __ast_encrypt_bin(unsigned char *dst, const unsigned char *src, int s
        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 @@ static int __ast_sign(struct ast_key *key, char *msg, char *sig)
        
 }
 
+/*!
+ * \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 @@ static int __ast_check_signature_bin(struct ast_key *key, const char *msg, int m
        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 @@ static int __ast_check_signature(struct ast_key *key, const char *msg, const cha
        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 @@ static void md52sum(char *sum, unsigned char *md5)
                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 @@ static int show_keys(int fd, int argc, char *argv[])
        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 @@ static struct ast_cli_entry cli_crypto[] = {
        init_keys_usage },
 };
 
+/*! \brief initialise the res_crypto module */
 static int crypto_init(void)
 {
        SSL_library_init();
index 7397218..2a4f38a 100644 (file)
@@ -80,8 +80,11 @@ char *playtones_desc=
  * 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 @@ static int handle_add_indication(int fd, int argc, char *argv[])
        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 @@ static int handle_remove_indication(int fd, int argc, char *argv[])
        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 @@ static int handle_show_indications(int fd, int argc, char *argv[])
        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 @@ static int handle_playtones(struct ast_channel *chan, void *data)
        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 @@ static int handle_stopplaytones(struct ast_channel *chan, void *data)
        return 0;
 }
 
-/*
- * Load module stuff
- */
+/*! \brief load indications module */
 static int ind_load_module(void)
 {
        struct ast_config *cfg;
@@ -342,9 +353,7 @@ out:                        v = v->next;
        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 @@ static struct ast_cli_entry cli_indications[] = {
        help_show_indications },
 };
 
-/*
- * Standard module functions ...
- */
+/*! \brief Unload indicators module */
 static int unload_module(void)
 {
        /* remove the registed indications... */
@@ -375,6 +382,7 @@ static int unload_module(void)
 }
 
 
+/*! \brief Load indications module */
 static int load_module(void)
 {
        if (ind_load_module())
@@ -386,6 +394,7 @@ static int load_module(void)
        return 0;
 }
 
+/*! \brief Reload indications module */
 static int reload(void)
 {
        /* remove the registed indications... */
index cc47010..6a73301 100644 (file)
@@ -115,6 +115,13 @@ static char *unpausemonitor_descrip = "UnpauseMonitor\n"
        "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 @@ static int ast_monitor_set_state(struct ast_channel *chan, int state)
  * \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 @@ int ast_monitor_start(      struct ast_channel *chan, const char *format_spec,
        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 @@ static const char *get_soxmix_format(const char *format)
        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 @@ int ast_monitor_stop(struct ast_channel *chan, int need_lock)
 }
 
 
-/* Pause monitoring of a channel */
+/*! \brief Pause monitoring of channel */
 int ast_monitor_pause(struct ast_channel *chan)
 {
        return ast_monitor_set_state(chan, AST_MONITOR_PAUSED);
 }
 
-/* Unpause monitoring of a channel */
+/*! \brief Unpause monitoring of channel */
 int ast_monitor_unpause(struct ast_channel *chan)
 {
        return ast_monitor_set_state(chan, AST_MONITOR_RUNNING);
 }
 
+/*! \brief Wrapper for ast_monitor_pause */
 static int pause_monitor_exec(struct ast_channel *chan, void *data)
 {
        return ast_monitor_pause(chan);
 }
 
+/*! \brief Wrapper for ast_monitor_unpause */
 static int unpause_monitor_exec(struct ast_channel *chan, void *data)
 {
        return ast_monitor_unpause(chan);
 }
 
-/* Change monitoring filename of a channel */
+/*! 
+ * \brief Change monitored filename of channel 
+ * \param chan
+ * \param fname_base new filename
+ * \param need_lock
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 int ast_monitor_change_fname(struct ast_channel *chan, const char *fname_base, int need_lock)
 {
        if (ast_strlen_zero(fname_base)) {
@@ -390,6 +417,14 @@ int ast_monitor_change_fname(struct ast_channel *chan, const char *fname_base, i
        return 0;
 }
 
+/*!
+ * \brief Start monitor
+ * \param chan
+ * \param data arguements passed  fname|options
+ * \retval 0 on success.
+ * \retval -1 on failure.
+*/
 static int start_monitor_exec(struct ast_channel *chan, void *data)
 {
        char *arg = NULL;
@@ -470,11 +505,13 @@ static int start_monitor_exec(struct ast_channel *chan, void *data)
        return res;
 }
 
+/*! \brief Wrapper function \see ast_monitor_stop */
 static int stop_monitor_exec(struct ast_channel *chan, void *data)
 {
        return ast_monitor_stop(chan, 1);
 }
 
+/*! \brief Wrapper function \see ast_monitor_change_fname */
 static int change_monitor_exec(struct ast_channel *chan, void *data)
 {
        return ast_monitor_change_fname(chan, (const char*)data, 1);
@@ -494,6 +531,7 @@ static char start_monitor_action_help[] =
 "                the input and output channels together after the\n"
 "                recording is finished.\n";
 
+/*! \brief Start monitoring a channel by manager connection */
 static int start_monitor_action(struct mansession *s, const struct message *m)
 {
        struct ast_channel *c = NULL;
@@ -547,6 +585,7 @@ static char stop_monitor_action_help[] =
 "  started 'Monitor' action.  The only parameter is 'Channel', the name\n"
 "  of the channel monitored.\n";
 
+/*! \brief Stop monitoring a channel by manager connection */
 static int stop_monitor_action(struct mansession *s, const struct message *m)
 {
        struct ast_channel *c = NULL;
@@ -579,6 +618,7 @@ static char change_monitor_action_help[] =
 "  File        - Required.  Is the new name of the file created in the\n"
 "                monitor spool directory.\n";
 
+/*! \brief Change filename of a monitored channel by manager connection */
 static int change_monitor_action(struct mansession *s, const struct message *m)
 {
        struct ast_channel *c = NULL;
index a0be455..b820c98 100644 (file)
@@ -40,6 +40,10 @@ int res_snmp_enabled;
 
 static pthread_t thread = AST_PTHREADT_NULL;
 
+/*!
+ * \brief Load res_snmp.conf config file
+ * \return 1 on load, 0 file does not exist
+*/
 static int load_config(void)
 {
        struct ast_variable *var;