From 75d387acbc19d236e8417b09ea6a53f6e4e45217 Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Sat, 24 Feb 2007 20:29:41 +0000 Subject: Doxygen additions, corrections git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@56665 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- apps/app_amd.c | 8 +++ apps/app_meetme.c | 1 + channels/chan_h323.c | 141 +++++++++++++++++++++-------------------- include/asterisk/ael_structs.h | 27 +++++++- include/asterisk/config.h | 3 + include/asterisk/doxyref.h | 2 +- include/asterisk/http.h | 1 + include/asterisk/jingle.h | 9 +++ include/asterisk/utils.h | 23 +++---- include/asterisk/zapata.h | 5 ++ main/channel.c | 24 +++++-- main/config.c | 1 + main/rtp.c | 10 +-- pbx/pbx_ael.c | 4 +- res/res_limit.c | 8 +++ 15 files changed, 170 insertions(+), 97 deletions(-) diff --git a/apps/app_amd.c b/apps/app_amd.c index e5dee1efc..0ab10dd9c 100644 --- a/apps/app_amd.c +++ b/apps/app_amd.c @@ -19,6 +19,14 @@ * this code. */ +/*! \file + * + * \brief Answering machine detection + * + * \author Claude Klimos (claude.klimos@aheeva.com) + */ + + #include "asterisk.h" ASTERISK_FILE_VERSION(__FILE__, "$Revision$") diff --git a/apps/app_meetme.c b/apps/app_meetme.c index 7f73b3bc7..2449edb42 100644 --- a/apps/app_meetme.c +++ b/apps/app_meetme.c @@ -334,6 +334,7 @@ struct volume { int actual; /*!< Actual volume adjustment (for channels that can't adjust) */ }; +/*! \brief The MeetMe User object */ struct ast_conf_user { int user_no; /*!< User Number */ int userflags; /*!< Flags as set in the conference */ diff --git a/channels/chan_h323.c b/channels/chan_h323.c index 8f9278cd8..1a2c4f057 100644 --- a/channels/chan_h323.c +++ b/channels/chan_h323.c @@ -120,10 +120,9 @@ setcapabilities_cb on_setcapabilities; setpeercapabilities_cb on_setpeercapabilities; onhold_cb on_hold; -/* global debug flag */ -int h323debug; +int h323debug; /*!< global debug flag */ -/*! Global jitterbuffer configuration - by default, jb is disabled */ +/*! \brief Global jitterbuffer configuration - by default, jb is disabled */ static struct ast_jb_conf default_jbconf = { .flags = 0, @@ -156,79 +155,81 @@ static unsigned int unique = 0; static call_options_t global_options; -/** Private structure of a OpenH323 channel */ +/*! \brief Private structure of a OpenH323 channel */ struct oh323_pvt { - ast_mutex_t lock; /* Channel private lock */ - call_options_t options; /* Options to be used during call setup */ - int alreadygone; /* Whether or not we've already been destroyed by our peer */ - int needdestroy; /* if we need to be destroyed */ - call_details_t cd; /* Call details */ - struct ast_channel *owner; /* Who owns us */ - struct sockaddr_in sa; /* Our peer */ - struct sockaddr_in redirip; /* Where our RTP should be going if not to us */ - int nonCodecCapability; /* non-audio capability */ - int outgoing; /* Outgoing or incoming call? */ - char exten[AST_MAX_EXTENSION]; /* Requested extension */ - char context[AST_MAX_CONTEXT]; /* Context where to start */ - char accountcode[256]; /* Account code */ - char rdnis[80]; /* Referring DNIS, if available */ - int amaflags; /* AMA Flags */ - struct ast_rtp *rtp; /* RTP Session */ - struct ast_dsp *vad; /* Used for in-band DTMF detection */ - int nativeformats; /* Codec formats supported by a channel */ - int needhangup; /* Send hangup when Asterisk is ready */ - int hangupcause; /* Hangup cause from OpenH323 layer */ - int newstate; /* Pending state change */ - int newcontrol; /* Pending control to send */ - int newdigit; /* Pending DTMF digit to send */ - int newduration; /* Pending DTMF digit duration to send */ - int pref_codec; /* Preferred codec */ - int peercapability; /* Capabilities learned from peer */ - int jointcapability; /* Common capabilities for local and remote side */ - struct ast_codec_pref peer_prefs; /* Preferenced list of codecs which remote side supports */ - int dtmf_pt[2]; /* Payload code used for RFC2833/CISCO messages */ - int curDTMF; /* DTMF tone being generated to Asterisk side */ - int DTMFsched; /* Scheduler descriptor for DTMF */ - int update_rtp_info; /* Configuration of fd's array is pending */ - int recvonly; /* Peer isn't wish to receive our voice stream */ - int txDtmfDigit; /* DTMF digit being to send to H.323 side */ - int noInbandDtmf; /* Inband DTMF processing by DSP isn't available */ - int connection_established; /* Call got CONNECT message */ - int got_progress; /* Call got PROGRESS message, pass inband audio */ - struct oh323_pvt *next; /* Next channel in list */ + ast_mutex_t lock; /*!< Channel private lock */ + call_options_t options; /*!nativeformats != pvt->nativeformats) { @@ -402,7 +403,7 @@ static void __oh323_update_info(struct ast_channel *c, struct oh323_pvt *pvt) } } -/* Only channel structure should be locked */ +/*! \brief Only channel structure should be locked */ static void oh323_update_info(struct ast_channel *c) { struct oh323_pvt *pvt = c->tech_pvt; @@ -546,7 +547,7 @@ static int oh323_digit_begin(struct ast_channel *c, char digit) return 0; } -/** +/*! \brief * Send (play) the specified digit to the channel. * */ @@ -584,7 +585,7 @@ static int oh323_digit_end(struct ast_channel *c, char digit, unsigned int durat return 0; } -/** +/*! \brief * Make a call over the specified channel to the specified * destination. * Returns -1 on error, 0 on success. @@ -757,9 +758,9 @@ static int oh323_hangup(struct ast_channel *c) return 0; } +/*! \brief Retrieve audio/etc from channel. Assumes pvt->lock is already held. */ static struct ast_frame *oh323_rtp_read(struct oh323_pvt *pvt) { - /* Retrieve audio/etc from channel. Assumes pvt->lock is already held. */ struct ast_frame *f; /* Only apply it for the first packet, we just need the correct ip/port */ @@ -1004,7 +1005,7 @@ static int __oh323_rtp_create(struct oh323_pvt *pvt) return 0; } -/* Private structure should be locked on a call */ +/*! \brief Private structure should be locked on a call */ static struct ast_channel *__oh323_new(struct oh323_pvt *pvt, int state, const char *host) { struct ast_channel *ch; @@ -1811,7 +1812,7 @@ static struct ast_channel *oh323_request(const char *type, int format, void *dat return tmpc; } -/** Find a call by alias */ +/*! \brief Find a call by alias */ static struct oh323_alias *find_alias(const char *source_aliases, int realtime) { struct oh323_alias *a; @@ -1824,7 +1825,7 @@ static struct oh323_alias *find_alias(const char *source_aliases, int realtime) return a; } -/** +/*! \brief * Callback for sending digits from H.323 up to asterisk * */ @@ -1895,10 +1896,10 @@ static int receive_digit(unsigned call_reference, char digit, const char *token, return res; } -/** +/*! \brief * Callback function used to inform the H.323 stack of the local rtp ip/port details * - * Returns the local RTP information + * \return Returns the local RTP information */ static struct rtp_info *external_rtp_create(unsigned call_reference, const char * token) { @@ -1936,7 +1937,7 @@ static struct rtp_info *external_rtp_create(unsigned call_reference, const char return info; } -/** +/*! \brief * Definition taken from rtp.c for rtpPayloadType because we need it here. */ struct rtpPayloadType { @@ -1944,7 +1945,7 @@ struct rtpPayloadType { int code; }; -/** +/*! \brief * Call-back function passing remote ip/port information from H.323 to asterisk * * Returns nothing @@ -2054,7 +2055,7 @@ static void setup_rtp_connection(unsigned call_reference, const char *remoteIp, return; } -/** +/*! \brief * Call-back function to signal asterisk that the channel has been answered * Returns nothing */ @@ -2108,7 +2109,7 @@ static int progress(unsigned call_reference, const char *token, int inband) return 0; } -/** +/*! \brief * Call-back function for incoming calls * * Returns 1 on success @@ -2228,7 +2229,7 @@ static call_options_t *setup_incoming_call(call_details_t *cd) return &pvt->options; } -/** +/*! \brief * Call-back function to start PBX when OpenH323 ready to serve incoming call * * Returns 1 on success @@ -2307,7 +2308,7 @@ static int answer_call(unsigned call_reference, const char *token) return 1; } -/** +/*! \brief * Call-back function to establish an outgoing H.323 call * * Returns 1 on success @@ -2320,7 +2321,7 @@ static int setup_outgoing_call(call_details_t *cd) return 1; } -/** +/*! \brief * Call-back function to signal asterisk that the channel is ringing * Returns nothing */ @@ -2346,7 +2347,7 @@ static void chan_ringing(unsigned call_reference, const char *token) return; } -/** +/*! \brief * Call-back function to cleanup communication * Returns nothing, */ diff --git a/include/asterisk/ael_structs.h b/include/asterisk/ael_structs.h index e17d302ee..d778baa99 100644 --- a/include/asterisk/ael_structs.h +++ b/include/asterisk/ael_structs.h @@ -1,3 +1,27 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 1999 - 2007, Digium, Inc. + * + * Mark Spencer + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! \file + * \brief Structures for AEL - the Asterisk extension language + * + * \ref pbx_ael.c + */ + #ifndef _ASTERISK_AEL_STRUCTS_H #define _ASTERISK_AEL_STRUCTS_H @@ -22,8 +46,7 @@ # endif -typedef enum -{ +typedef enum { PV_WORD, /* an ident, string, name, label, etc. A user-supplied string. */ /* 0 */ PV_MACRO, /* 1 */ PV_CONTEXT, /* 2 */ diff --git a/include/asterisk/config.h b/include/asterisk/config.h index c9b684cb6..5e1a6fc72 100644 --- a/include/asterisk/config.h +++ b/include/asterisk/config.h @@ -33,6 +33,8 @@ struct ast_config; struct ast_category; +/*! \brief Structure for variables, used for configurations and for channel variables +*/ struct ast_variable { char *name; char *value; @@ -50,6 +52,7 @@ typedef struct ast_variable *realtime_var_get(const char *database, const char * typedef struct ast_config *realtime_multi_get(const char *database, const char *table, va_list ap); typedef int realtime_update(const char *database, const char *table, const char *keyfield, const char *entity, va_list ap); +/*! \brief Configuration engine structure, used to define realtime drivers */ struct ast_config_engine { char *name; config_load_func *load_func; diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index fa4d1ac3a..af949a7c4 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -16,7 +16,7 @@ * at the top of the source tree. */ -/* \file This file generates Doxygen pages from files in the /doc +/*! \file This file generates Doxygen pages from files in the /doc directory of the Asterisk source code tree */ diff --git a/include/asterisk/http.h b/include/asterisk/http.h index 4cc159be4..94befbc00 100644 --- a/include/asterisk/http.h +++ b/include/asterisk/http.h @@ -147,6 +147,7 @@ int ssl_setup(struct tls_config *cfg); */ typedef struct ast_str *(*ast_http_callback)(struct sockaddr_in *requestor, const char *uri, struct ast_variable *params, int *status, char **title, int *contentlength); +/*! \brief Definition of a URI reachable in the embedded HTTP server */ struct ast_http_uri { AST_LIST_ENTRY(ast_http_uri) entry; const char *description; diff --git a/include/asterisk/jingle.h b/include/asterisk/jingle.h index 0968b7394..222ca510b 100644 --- a/include/asterisk/jingle.h +++ b/include/asterisk/jingle.h @@ -16,6 +16,15 @@ * at the top of the source tree. */ +/*! \file + * \brief Jingle definitions for chan_jingle + * + * \ref chan_jingle.c + * + * \author Matt O'Gorman + */ + + #ifndef _ASTERISK_JINGLE_H #define _ASTERISK_JINGLE_H diff --git a/include/asterisk/utils.h b/include/asterisk/utils.h index fbda15757..8981824eb 100644 --- a/include/asterisk/utils.h +++ b/include/asterisk/utils.h @@ -39,8 +39,8 @@ #include "asterisk/logger.h" #include "asterisk/compiler.h" -/*! \note - \verbatim +/*! +\note \verbatim Note: It is very important to use only unsigned variables to hold bit flags, as otherwise you can fall prey to the compiler's @@ -141,6 +141,8 @@ extern unsigned int __unsigned_int_flags_dummy; #define AST_FLAGS_ALL UINT_MAX +/*! \brief Structure used to handle boolean flags +*/ struct ast_flags { unsigned int flags; }; @@ -150,22 +152,21 @@ struct ast_hostent { char buf[1024]; }; +/*! \brief Thread-safe gethostbyname function to use in Asterisk */ struct hostent *ast_gethostbyname(const char *host, struct ast_hostent *hp); -/* ast_md5_hash - \brief Produces MD5 hash based on input string */ +/*! \brief Produces MD5 hash based on input string */ void ast_md5_hash(char *output, char *input); -/* ast_sha1_hash - \brief Produces SHA1 hash based on input string */ +/*! \brief Produces SHA1 hash based on input string */ void ast_sha1_hash(char *output, char *input); int ast_base64encode_full(char *dst, const unsigned char *src, int srclen, int max, int linebreaks); int ast_base64encode(char *dst, const unsigned char *src, int srclen, int max); int ast_base64decode(unsigned char *dst, const char *src, int max); -/*! ast_uri_encode - \brief Turn text string to URI-encoded %XX version - At this point, we're converting from ISO-8859-x (8-bit), not UTF8 +/*! \brief Turn text string to URI-encoded %XX version + +\note At this point, we're converting from ISO-8859-x (8-bit), not UTF8 as in the SIP protocol spec If doreserved == 1 we will convert reserved characters also. RFC 2396, section 2.4 @@ -238,7 +239,7 @@ const char *ast_inet_ntoa(struct in_addr ia); int ast_utils_init(void); int ast_wait_for_input(int fd, int ms); -/*! ast_carefulwrite +/*! \brief Try to write string, but wait no more than ms milliseconds before timing out. @@ -249,7 +250,7 @@ int ast_wait_for_input(int fd, int ms); */ int ast_carefulwrite(int fd, char *s, int len, int timeoutms); -/*! Compares the source address and port of two sockaddr_in */ +/*! \brief Compares the source address and port of two sockaddr_in */ static force_inline int inaddrcmp(const struct sockaddr_in *sin1, const struct sockaddr_in *sin2) { return ((sin1->sin_addr.s_addr != sin2->sin_addr.s_addr) diff --git a/include/asterisk/zapata.h b/include/asterisk/zapata.h index 0f13a258a..8d7eff74f 100644 --- a/include/asterisk/zapata.h +++ b/include/asterisk/zapata.h @@ -17,6 +17,11 @@ * for less than ten lines of preprocessor directives... */ +/*! \file + * \brief Stub to find zaptel headers + */ + + /* * Stub to find the zaptel headers. The configure script will * define HAVE_ZAPTEL_VERSION according to what it has found. diff --git a/main/channel.c b/main/channel.c index 2ab07b7e5..a18251d84 100644 --- a/main/channel.c +++ b/main/channel.c @@ -72,12 +72,15 @@ struct channel_spy_trans { struct ast_trans_pvt *path; }; +/*! \brief List of SPY structures +*/ struct ast_channel_spy_list { struct channel_spy_trans read_translator; struct channel_spy_trans write_translator; AST_LIST_HEAD_NOLOCK(, ast_channel_spy) list; }; +/*! \brief Definition of the Whisper buffer */ struct ast_channel_whisper_buffer { ast_mutex_t lock; struct ast_slinfactory sf; @@ -88,10 +91,10 @@ struct ast_channel_whisper_buffer { /* uncomment if you have problems with 'monitoring' synchronized files */ #if 0 #define MONITOR_CONSTANT_DELAY -#define MONITOR_DELAY 150 * 8 /* 150 ms of MONITORING DELAY */ +#define MONITOR_DELAY 150 * 8 /*!< 150 ms of MONITORING DELAY */ #endif -/*! Prevent new channel allocation if shutting down. */ +/*! \brief Prevent new channel allocation if shutting down. */ static int shutting_down; static int uniqueint; @@ -101,22 +104,25 @@ unsigned long global_fin, global_fout; AST_THREADSTORAGE(state2str_threadbuf); #define STATE2STR_BUFSIZE 32 -/*! 100ms */ -#define AST_DEFAULT_EMULATE_DTMF_DURATION 100 +#define AST_DEFAULT_EMULATE_DTMF_DURATION 100 /*!< 100ms */ +/*! \brief List of channel drivers */ struct chanlist { const struct ast_channel_tech *tech; AST_LIST_ENTRY(chanlist) list; }; -/*! the list of registered channel types */ +/*! \brief the list of registered channel types */ static AST_LIST_HEAD_NOLOCK_STATIC(backends, chanlist); -/*! the list of channels we have. Note that the lock for this list is used for +/*! \brief the list of channels we have. Note that the lock for this list is used for both the channels list and the backends list. */ static AST_LIST_HEAD_STATIC(channels, ast_channel); -/*! map AST_CAUSE's to readable string representations */ +/*! \brief map AST_CAUSE's to readable string representations + * + * \ref causes.h +*/ const struct ast_cause { int cause; const char *name; @@ -184,6 +190,7 @@ struct ast_variable *ast_channeltype_list(void) return var; } +/*! \brief Show channel types - CLI command */ static int show_channeltypes(int fd, int argc, char *argv[]) { #define FORMAT "%-10.10s %-40.40s %-12.12s %-12.12s %-12.12s\n" @@ -211,6 +218,7 @@ static int show_channeltypes(int fd, int argc, char *argv[]) } +/*! \brief Show details about a channel driver - CLI command */ static int show_channeltype(int fd, int argc, char *argv[]) { struct chanlist *cl = NULL; @@ -428,6 +436,7 @@ int ast_channel_register(const struct ast_channel_tech *tech) return 0; } +/*! \brief Unregister channel driver */ void ast_channel_unregister(const struct ast_channel_tech *tech) { struct chanlist *chan; @@ -451,6 +460,7 @@ void ast_channel_unregister(const struct ast_channel_tech *tech) AST_LIST_UNLOCK(&channels); } +/*! \brief Get handle to channel driver based on name */ const struct ast_channel_tech *ast_get_channel_tech(const char *name) { struct chanlist *chanls; diff --git a/main/config.c b/main/config.c index 023be5fb5..ee9d03a0d 100644 --- a/main/config.c +++ b/main/config.c @@ -70,6 +70,7 @@ static char *lline_buffer; /*!< A buffer for stuff behind the ; */ static int lline_buffer_size; +/*! \brief Structure to keep comments for rewriting configuration files */ struct ast_comment { struct ast_comment *next; char cmt[0]; diff --git a/main/rtp.c b/main/rtp.c index afb5c256a..728eaa849 100644 --- a/main/rtp.c +++ b/main/rtp.c @@ -3277,10 +3277,6 @@ static enum ast_bridge_result bridge_p2p_loop(struct ast_channel *c0, struct ast return res; } -/*! \brief Bridge calls. If possible and allowed, initiate - re-invite so the peers exchange media directly outside - of Asterisk. -*/ /*! \page AstRTPbridge The Asterisk RTP bridge The RTP bridge is called from the channel drivers that are using the RTP subsystem in Asterisk - like SIP, H.323 and Jingle/Google Talk. @@ -3306,6 +3302,12 @@ static enum ast_bridge_result bridge_p2p_loop(struct ast_channel *c0, struct ast - ast_rtp_bridge() - ast_channel_early_bridge() - ast_channel_bridge() + - rtp.c + - rtp.h +*/ +/*! \brief Bridge calls. If possible and allowed, initiate + re-invite so the peers exchange media directly outside + of Asterisk. */ enum ast_bridge_result ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms) { diff --git a/pbx/pbx_ael.c b/pbx/pbx_ael.c index 8c14e918b..02bf99f3d 100644 --- a/pbx/pbx_ael.c +++ b/pbx/pbx_ael.c @@ -70,7 +70,7 @@ static int notes; development, this code can be properly re-instated */ -/* null definitions for structs passed down the infrastructure */ +/*! \brief null definitions for structs passed down the infrastructure */ struct argapp { struct argapp *next; @@ -151,7 +151,7 @@ static pval *get_contxt(pval *p); static void remove_spaces_before_equals(char *str); static void substitute_commas(char *str); -/* I am adding this code to substitute commas with vertbars in the args to apps */ +/*! \brief I am adding this code to substitute commas with vertbars in the args to apps */ static void substitute_commas(char *str) { char *p = str; diff --git a/res/res_limit.c b/res/res_limit.c index d76ad4003..045f8db69 100644 --- a/res/res_limit.c +++ b/res/res_limit.c @@ -11,6 +11,14 @@ * */ +/*! \file + * + * \brief Resource limits + * + * \author Tilghman Lesher + */ + + #include "asterisk.h" #include -- cgit v1.2.3