Doxygen updates
authorOlle Johansson <oej@edvina.net>
Tue, 5 Dec 2006 20:39:13 +0000 (20:39 +0000)
committerOlle Johansson <oej@edvina.net>
Tue, 5 Dec 2006 20:39:13 +0000 (20:39 +0000)
git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@48277 65c4cc65-6c06-0410-ace0-fbb531ad65f3

include/asterisk/channel.h
include/asterisk/rtp.h
main/rtp.c

index ff0901f..c83d209 100644 (file)
        \arg translate.h - Transcoding support functions
        \arg \ref channel_drivers - Implemented channel drivers
        \arg \ref Def_Frame Asterisk Multimedia Frames
+       \arg \ref Def_Bridge
 
 */
+/*! \page Def_Bridge Asterisk Channel Bridges
+
+       In Asterisk, there's several media bridges. 
+
+       The Core bridge handles two channels (a "phone call") and bridge
+       them together.
+       
+       The conference bridge (meetme) handles several channels simultaneosly
+       with the support of an external timer (zaptel timer). This is used
+       not only by the Conference application (meetme) but also by the
+       page application and the SLA system introduced in 1.4.
+       The conference bridge does not handle video.
+
+       When two channels of the same type connect, the channel driver
+       or the media subsystem used by the channel driver (i.e. RTP)
+       can create a native bridge without sending media through the
+       core.
+
+       Native briding can be disabled by a number of reasons,
+       like DTMF being needed by the core or codecs being incompatible
+       so a transcoding module is needed.
+
+References:
+        - ast_channel_early_bridge()
+        - ast_channel_bridge()
+       - app_meetme.c
+       - \ref AstRTPbridge
+        - ast_rtp_bridge() 
+       - \ref Def_Channel
+*/
 
 /*! \page AstFileDesc File descriptors 
        Asterisk File descriptors are connected to each channel (see \ref Def_Channel)
index f7c1718..79de670 100644 (file)
@@ -48,8 +48,11 @@ extern "C" {
 /*! Maximum RTP-specific code */
 #define AST_RTP_MAX                    AST_RTP_CISCO_DTMF
 
+/*! Maxmum number of payload defintions for a RTP session */
 #define MAX_RTP_PT                     256
 
+#define FLAG_3389_WARNING              (1 << 0)
+
 enum ast_rtp_options {
        AST_RTP_OPT_G726_NONSTANDARD = (1 << 0),
 };
@@ -65,6 +68,8 @@ enum ast_rtp_get_result {
 
 struct ast_rtp;
 
+/*! \brief This is the structure that binds a channel (SIP/Jingle/H.323) to the RTP subsystem 
+*/
 struct ast_rtp_protocol {
        /*! Get RTP struct, or NULL if unwilling to transfer */
        enum ast_rtp_get_result (* const get_rtp_info)(struct ast_channel *chan, struct ast_rtp **rtp);
@@ -78,8 +83,7 @@ struct ast_rtp_protocol {
 };
 
 
-#define FLAG_3389_WARNING              (1 << 0)
-
+/*! RTP callback structure */
 typedef int (*ast_rtp_callback)(struct ast_rtp *rtp, struct ast_frame *f, void *data);
 
 /*!
@@ -122,11 +126,13 @@ void ast_rtp_get_us(struct ast_rtp *rtp, struct sockaddr_in *us);
 
 struct ast_rtp *ast_rtp_get_bridged(struct ast_rtp *rtp);
 
+/*! Destroy RTP session */
 void ast_rtp_destroy(struct ast_rtp *rtp);
 
 void ast_rtp_reset(struct ast_rtp *rtp);
 
-void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
+/*! Stop RTP session, do not destroy structure */
+void ast_rtp_stop(struct ast_rtp *rtp);
 
 void ast_rtp_set_callback(struct ast_rtp *rtp, ast_rtp_callback callback);
 
@@ -189,10 +195,18 @@ void ast_rtp_setdtmfcompensate(struct ast_rtp *rtp, int compensate);
 /*! \brief Enable STUN capability */
 void ast_rtp_setstun(struct ast_rtp *rtp, int stun_enable);
 
+/*! \brief Send STUN request (??) */
+void ast_rtp_stun_request(struct ast_rtp *rtp, struct sockaddr_in *suggestion, const char *username);
+
+/*! \brief The RTP bridge.
+       \arg \ref AstRTPbridge
+*/
 int ast_rtp_bridge(struct ast_channel *c0, struct ast_channel *c1, int flags, struct ast_frame **fo, struct ast_channel **rc, int timeoutms);
 
+/*! \brief Register an RTP channel client */
 int ast_rtp_proto_register(struct ast_rtp_protocol *proto);
 
+/*! \brief Unregister an RTP channel client */
 void ast_rtp_proto_unregister(struct ast_rtp_protocol *proto);
 
 int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, int media);
@@ -201,22 +215,22 @@ int ast_rtp_make_compatible(struct ast_channel *dest, struct ast_channel *src, i
            having to send a re-invite later */
 int ast_rtp_early_bridge(struct ast_channel *c0, struct ast_channel *c1);
 
-void ast_rtp_stop(struct ast_rtp *rtp);
 
-/*! \brief Return RTCP quality string */
-char *ast_rtp_get_quality(struct ast_rtp *rtp);
 
 /*! \brief Send an H.261 fast update request. Some devices need this rather than the XML message  in SIP */
 int ast_rtcp_send_h261fur(void *data);
 
-void ast_rtp_init(void);
-
-int ast_rtp_reload(void);
+char *ast_rtp_get_quality(struct ast_rtp *rtp);              /*! \brief Return RTCP quality string */
+void ast_rtp_init(void);                                      /*! Initialize RTP subsystem */
+int ast_rtp_reload(void);                                     /*! reload rtp configuration */
 
+/*! Set codec preference */
 int ast_rtp_codec_setpref(struct ast_rtp *rtp, struct ast_codec_pref *prefs);
 
+/*! Get codec preference */
 struct ast_codec_pref *ast_rtp_codec_getpref(struct ast_rtp *rtp);
 
+/*! get format from predefined dynamic payload format */
 int ast_rtp_codec_getformat(int pt);
 
 /*! \brief Set rtp timeout */
index c629da0..7163f16 100644 (file)
@@ -3142,7 +3142,34 @@ static enum ast_bridge_result bridge_p2p_loop(struct ast_channel *c0, struct ast
 
 /*! \brief Bridge calls. If possible and allowed, initiate
        re-invite so the peers exchange media directly outside 
-       of Asterisk. */
+       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.
+
+       This bridge aims to offload the Asterisk server by setting up
+       the media stream directly between the endpoints, keeping the
+       signalling in Asterisk.
+
+       It checks with the channel driver, using a callback function, if
+       there are possibilities for a remote bridge.
+
+       If this fails, the bridge hands off to the core bridge. Reasons
+       can be NAT support needed, DTMF features in audio needed by
+       the PBX for transfers or spying/monitoring on channels.
+
+       If transcoding is needed - we can't do a remote bridge.
+       If only NAT support is needed, we're using Asterisk in
+       RTP proxy mode with the p2p RTP bridge, basically
+       forwarding incoming audio packets to the outbound
+       stream on a network level.
+
+       References:
+       - ast_rtp_bridge()
+       - ast_channel_early_bridge()
+       - ast_channel_bridge()
+*/
 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)
 {
        struct ast_rtp *p0 = NULL, *p1 = NULL;          /* Audio RTP Channels */