From 44a124d9f6fcf4ecef9574aa66bf26b4f5018f57 Mon Sep 17 00:00:00 2001 From: Benny Prijono Date: Wed, 18 Oct 2006 12:50:46 +0000 Subject: Updated doxygen documentation for media transport (again) git-svn-id: http://svn.pjsip.org/repos/pjproject/trunk@779 74dad513-b988-da41-8d7b-12977e46ad98 --- pjmedia/include/pjmedia/transport.h | 75 +++++++++++++++++++++++++++---------- 1 file changed, 56 insertions(+), 19 deletions(-) diff --git a/pjmedia/include/pjmedia/transport.h b/pjmedia/include/pjmedia/transport.h index 4b8d3158..bc0cf226 100644 --- a/pjmedia/include/pjmedia/transport.h +++ b/pjmedia/include/pjmedia/transport.h @@ -57,44 +57,81 @@ * * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport * - * The media transport's life-cycle normally follows the following stages: - * - application creates the media transport when it needs to establish + * The media transport's life-cycle normally follows the following stages. + * + * \subsection PJMEDIA_TRANSPORT_H_CREATE Creating the Media Transport + * + * Application creates the media transport when it needs to establish * media session to remote peer. The media transport is created using * specific function to create that particular transport; for example, * for UDP media transport, it is created with #pjmedia_transport_udp_create() * or #pjmedia_transport_udp_create2() functions. Different media * transports will provide different API to create those transports. - * - application specifies this media transport instance when creating + * + * Alternatively, application may create pool of media transports when + * it is first started up. Using this approach probably is better, since + * application has to specify the RTP port when sending the initial + * session establishment request (e.g. SIP INVITE request), thus if + * application only creates the media transport later when media is to be + * established (normally when 200/OK is received, or when 18x is received + * for early media), there is a possibility that the particular RTP + * port might have been occupied by other programs. Also it is more + * efficient since sockets don't need to be closed and re-opened between + * calls. + * + * + * \subsection PJMEDIA_TRANSPORT_H_ATTACH Attaching and Using the Media Transport. + * + * Application specifies the media transport instance when creating * the media session (#pjmedia_session_create()). Alternatively, it * may create the media stream directly with #pjmedia_stream_create() - * and specify this transport instance in the argument. (Note: media + * and specify the transport instance in the argument. (Note: media * session is a high-level abstraction for media communications between - * two endpoints, and it may contain more than one media stream, for + * two endpoints, and it may contain more than one media streams, for * example, an audio stream and a video stream). - * - when stream is created, it will "attach" itself to the media + * + * When stream is created, it will "attach" itself to the media * transport by calling #pjmedia_transport_attach(), which is a thin * wrapper which calls "attach()" method of the media transport's * "virtual function pointer" (#pjmedia_transport_op). Among other things, - * the stream specifies two callback functions to be called: one + * the stream specifies two callback functions to the transport: one * callback function will be called by transport when it receives RTP - * packet, and another callback for incoming RTCP packet. - * - when the stream needs to send outgoing RTP/RTCP packets, it will - * call #pjmedia_transport_send_rtp() and #pjmedia_transport_send_rtcp(), - * which is a thin wrapper to call send_rtp() and send_rtcp() methods - * in the media transport's "virtual function pointer" - * (#pjmedia_transport_op). - * - when the stream is destroyed, it will "detach" itself from + * packet, and another callback for incoming RTCP packet. The + * #pjmedia_transport_attach() function also establish the destination + * of the outgoing RTP and RTCP packets. + * + * When the stream needs to send outgoing RTP/RTCP packets, it will + * call #pjmedia_transport_send_rtp() and #pjmedia_transport_send_rtcp() + * of the media transport API, which is a thin wrapper to call send_rtp() + * and send_rtcp() methods in the media transport's "virtual function + * pointer" (#pjmedia_transport_op). + * + * When the stream is destroyed, it will "detach" itself from * the media transport by calling #pjmedia_transport_detach(), which is * a thin wrapper which calls "detach()" method of the media transport's * "virtual function pointer" (#pjmedia_transport_op). After the transport * is detached from its user (the stream), it will no longer report - * incoming RTP/RTCP packets, since there is no "user" of the transport. - * - after transport has been detached, application may re-attach the - * transport to another stream if it wants to. - * - finally if application no longer needs the media transport, it will + * incoming RTP/RTCP packets to the stream, and it will refuse to send + * outgoing packets since the destination has been cleared. + * + * + * \subsection PJMEDIA_TRANSPORT_H_REUSE Reusing the Media Transport. + * + * After transport has been detached, application may re-attach the + * transport to another stream if it wants to. Detaching and re-attaching + * media transport may be preferable than closing and re-opening the + * transport, since it is more efficient (sockets don't need to be + * closed and re-opened). However it is up to the application to choose + * which method is most suitable for its uses. + * + * + * \subsection PJMEDIA_TRANSPORT_H_DESTROY Destroying the Media Transport. + * + * Finally if application no longer needs the media transport, it will * call #pjmedia_transport_close() function, which is thin wrapper which * calls "destroy()" method of the media transport's "virtual function - * pointer" (#pjmedia_transport_op). + * pointer" (#pjmedia_transport_op). This function releases + * all resources used by the transport, such as sockets and memory. * * * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport -- cgit v1.2.3