Changeset 779


Ignore:
Timestamp:
Oct 18, 2006 12:50:46 PM (14 years ago)
Author:
bennylp
Message:

Updated doxygen documentation for media transport (again)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • pjproject/trunk/pjmedia/include/pjmedia/transport.h

    r778 r779  
    5858 * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport 
    5959 * 
    60  * The media transport's life-cycle normally follows the following stages: 
    61  *  - application creates the media transport when it needs to establish 
     60 * The media transport's life-cycle normally follows the following stages. 
     61 * 
     62 * \subsection PJMEDIA_TRANSPORT_H_CREATE Creating the Media Transport 
     63 * 
     64 *  Application creates the media transport when it needs to establish 
    6265 *    media session to remote peer. The media transport is created using 
    6366 *    specific function to create that particular transport; for example, 
     
    6568 *    or #pjmedia_transport_udp_create2() functions. Different media 
    6669 *    transports will provide different API to create those transports. 
    67  *  - application specifies this media transport instance when creating 
     70 * 
     71 *  Alternatively, application may create pool of media transports when 
     72 *    it is first started up. Using this approach probably is better, since 
     73 *    application has to specify the RTP port when sending the initial 
     74 *    session establishment request (e.g. SIP INVITE request), thus if 
     75 *    application only creates the media transport later when media is to be 
     76 *    established (normally when 200/OK is received, or when 18x is received 
     77 *    for early media), there is a possibility that the particular RTP 
     78 *    port might have been occupied by other programs. Also it is more 
     79 *    efficient since sockets don't need to be closed and re-opened between 
     80 *    calls. 
     81 * 
     82 * 
     83 * \subsection PJMEDIA_TRANSPORT_H_ATTACH Attaching and Using the Media Transport. 
     84 * 
     85 *  Application specifies the media transport instance when creating 
    6886 *    the media session (#pjmedia_session_create()). Alternatively, it 
    6987 *    may create the media stream directly with #pjmedia_stream_create() 
    70  *    and specify this transport instance in the argument. (Note: media 
     88 *    and specify the transport instance in the argument. (Note: media 
    7189 *    session is a high-level abstraction for media communications between 
    72  *    two endpoints, and it may contain more than one media stream, for 
     90 *    two endpoints, and it may contain more than one media streams, for 
    7391 *    example, an audio stream and a video stream). 
    74  *  - when stream is created, it will "attach" itself to the media  
     92 * 
     93 *  When stream is created, it will "attach" itself to the media  
    7594 *    transport by calling #pjmedia_transport_attach(), which is a thin 
    7695 *    wrapper which calls "attach()" method of the media transport's  
    7796 *    "virtual function pointer" (#pjmedia_transport_op). Among other things, 
    78  *    the stream specifies two callback functions to be called: one 
     97 *    the stream specifies two callback functions to the transport: one 
    7998 *    callback function will be called by transport when it receives RTP 
    80  *    packet, and another callback for incoming RTCP packet. 
    81  *  - when the stream needs to send outgoing RTP/RTCP packets, it will 
    82  *    call #pjmedia_transport_send_rtp() and #pjmedia_transport_send_rtcp(), 
    83  *    which is a thin wrapper to call send_rtp() and send_rtcp() methods 
    84  *    in the media transport's "virtual function pointer"  
    85  *    (#pjmedia_transport_op). 
    86  *  - when the stream is destroyed, it will "detach" itself from 
     99 *    packet, and another callback for incoming RTCP packet. The  
     100 *    #pjmedia_transport_attach() function also establish the destination 
     101 *    of the outgoing RTP and RTCP packets. 
     102 * 
     103 *  When the stream needs to send outgoing RTP/RTCP packets, it will 
     104 *    call #pjmedia_transport_send_rtp() and #pjmedia_transport_send_rtcp() 
     105 *    of the media transport API, which is a thin wrapper to call send_rtp()  
     106 *    and send_rtcp() methods in the media transport's "virtual function  
     107 *    pointer"  (#pjmedia_transport_op). 
     108 * 
     109 *  When the stream is destroyed, it will "detach" itself from 
    87110 *    the media transport by calling #pjmedia_transport_detach(), which is 
    88111 *    a thin wrapper which calls "detach()" method of the media transport's  
    89112 *    "virtual function pointer" (#pjmedia_transport_op). After the transport 
    90113 *    is detached from its user (the stream), it will no longer report  
    91  *    incoming RTP/RTCP packets, since there is no "user" of the transport. 
    92  *  - after transport has been detached, application may re-attach the 
    93  *    transport to another stream if it wants to. 
    94  *  - finally if application no longer needs the media transport, it will 
     114 *    incoming RTP/RTCP packets to the stream, and it will refuse to send 
     115 *    outgoing packets since the destination has been cleared. 
     116 * 
     117 * 
     118 * \subsection PJMEDIA_TRANSPORT_H_REUSE Reusing the Media Transport. 
     119 * 
     120 *  After transport has been detached, application may re-attach the 
     121 *    transport to another stream if it wants to. Detaching and re-attaching 
     122 *    media transport may be preferable than closing and re-opening the 
     123 *    transport, since it is more efficient (sockets don't need to be 
     124 *    closed and re-opened). However it is up to the application to choose 
     125 *    which method is most suitable for its uses. 
     126 * 
     127 *  
     128 * \subsection PJMEDIA_TRANSPORT_H_DESTROY Destroying the Media Transport. 
     129 * 
     130 *  Finally if application no longer needs the media transport, it will 
    95131 *    call #pjmedia_transport_close() function, which is thin wrapper which  
    96132 *    calls "destroy()" method of the media transport's  "virtual function  
    97  *    pointer" (#pjmedia_transport_op).  
     133 *    pointer" (#pjmedia_transport_op). This function releases 
     134 *    all resources used by the transport, such as sockets and memory. 
    98135 * 
    99136 * 
Note: See TracChangeset for help on using the changeset viewer.