diff options
| -rw-r--r-- | channels/chan_sip.c | 2 | ||||
| -rw-r--r-- | include/asterisk.h | 10 | ||||
| -rw-r--r-- | include/asterisk/doxyref.h | 1 | ||||
| -rw-r--r-- | include/asterisk/file.h | 8 | ||||
| -rw-r--r-- | include/jitterbuf.h | 82 | ||||
| -rw-r--r-- | main/asterisk.c | 6 | ||||
| -rw-r--r-- | main/devicestate.c | 2 | ||||
| -rw-r--r-- | main/enum.c | 6 | ||||
| -rw-r--r-- | res/res_clioriginate.c | 36 | ||||
| -rw-r--r-- | res/res_config_odbc.c | 39 | ||||
| -rw-r--r-- | res/res_config_sqlite.c | 156 | ||||
| -rw-r--r-- | res/res_convert.c | 9 | ||||
| -rw-r--r-- | res/res_crypto.c | 85 | ||||
| -rw-r--r-- | res/res_indications.c | 47 | ||||
| -rw-r--r-- | res/res_monitor.c | 52 | ||||
| -rw-r--r-- | res/res_snmp.c | 4 |
16 files changed, 368 insertions, 177 deletions
diff --git a/channels/chan_sip.c b/channels/chan_sip.c index 90251ee8b..06613fcc5 100644 --- a/channels/chan_sip.c +++ b/channels/chan_sip.c @@ -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 diff --git a/include/asterisk.h b/include/asterisk.h index 6e20c16a9..7dd5897d3 100644 --- a/include/asterisk.h +++ b/include/asterisk.h @@ -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)); diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 3d0511804..bf538c6d8 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -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 */ - diff --git a/include/asterisk/file.h b/include/asterisk/file.h index 008759713..22a887c66 100644 --- a/include/asterisk/file.h +++ b/include/asterisk/file.h @@ -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 diff --git a/include/jitterbuf.h b/include/jitterbuf.h index d2635f3f0..d2e5b5ac0 100644 --- a/include/jitterbuf.h +++ b/include/jitterbuf.h @@ -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, ...); diff --git a/main/asterisk.c b/main/asterisk.c index 7f998123f..118dd2982 100644 --- a/main/asterisk.c +++ b/main/asterisk.c @@ -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 */ /*! @{ */ diff --git a/main/devicestate.c b/main/devicestate.c index a233e5686..05a775227 100644 --- a/main/devicestate.c +++ b/main/devicestate.c @@ -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 diff --git a/main/enum.c b/main/enum.c index 1c9d34184..cf298a655 100644 --- a/main/enum.c +++ b/main/enum.c @@ -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; diff --git a/res/res_clioriginate.c b/res/res_clioriginate.c index 44afd7b76..8497f6387 100644 --- a/res/res_clioriginate.c +++ b/res/res_clioriginate.c @@ -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)); diff --git a/res/res_config_odbc.c b/res/res_config_odbc.c index 28c8c316e..2c8b90e3d 100644 --- a/res/res_config_odbc.c +++ b/res/res_config_odbc.c @@ -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; diff --git a/res/res_config_sqlite.c b/res/res_config_sqlite.c index 9aa37d5f0..c9c65f881 100644 --- a/res/res_config_sqlite.c +++ b/res/res_config_sqlite.c @@ -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 *" diff --git a/res/res_convert.c b/res/res_convert.c index be3d177eb..34606ac24 100644 --- a/res/res_convert.c +++ b/res/res_convert.c @@ -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; diff --git a/res/res_crypto.c b/res/res_crypto.c index 73a54ba6d..1897ab1cf 100644 --- a/res/res_crypto.c +++ b/res/res_crypto.c @@ -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(); diff --git a/res/res_indications.c b/res/res_indications.c index 7397218dc..2a4f38a3a 100644 --- a/res/res_indications.c +++ b/res/res_indications.c @@ -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... */ diff --git a/res/res_monitor.c b/res/res_monitor.c index cc4701049..6a7330142 100644 --- a/res/res_monitor.c +++ b/res/res_monitor.c @@ -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; diff --git a/res/res_snmp.c b/res/res_snmp.c index a0be455ef..b820c98ac 100644 --- a/res/res_snmp.c +++ b/res/res_snmp.c @@ -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; |