Changeset 778 for pjproject/trunk


Ignore:
Timestamp:
Oct 18, 2006 10:01:25 AM (18 years ago)
Author:
bennylp
Message:

Updated doxygen documentation in media transport

File:
1 edited

Legend:

Unmodified
Added
Removed

  • pjproject/trunk/pjmedia/include/pjmedia/transport.h

    r568 r778  
    2929 
    3030/** 
    31  * @defgroup PJMEDIA_TRANSPORT Transports 
     31 * @defgroup PJMEDIA_TRANSPORT Media Transports 
    3232 * @ingroup PJMEDIA 
    3333 * @brief Transports. 
    … …  
    3636 
    3737/** 
    38  * @defgroup PJMEDIA_TRANSPORT_H Network Transport Interface 
     38 * @defgroup PJMEDIA_TRANSPORT_H Media Network Transport Interface 
    3939 * @ingroup PJMEDIA_TRANSPORT 
    4040 * @brief PJMEDIA object for sending/receiving media packets over the network 
    4141 * @{ 
    4242 * The media transport (#pjmedia_transport) is the object to send and 
    43  * receive media packets over the network. Currently only media @ref PJMED_STRM 
    44  * are using the transport. 
    45  * 
    46  * Although currently only @ref PJMEDIA_TRANSPORT_UDP is implemented, 
    47  * media transport interface is intended to support any custom transports. 
     43 * receive media packets over the network. The media transport interface 
     44 * allows the library to be extended to support different types of  
     45 * transports to send and receive packets. Currently only the standard 
     46 * UDP transport implementation is provided (see \ref PJMEDIA_TRANSPORT_UDP), 
     47 * but application designer may extend the library to support other types 
     48 * of custom transports such as RTP/RTCP over TCP, RTP/RTCP over HTTP, etc. 
     49 * 
     50 * The media transport is declared as #pjmedia_transport "class", which 
     51 * declares "interfaces" to use the class in #pjmedia_transport_op 
     52 * structure. For the user of the media transport (normally the user of 
     53 * media transport is media stream, see \ref PJMED_STRM), these transport 
     54 * "methods" are wrapped with API such as #pjmedia_transport_attach(), 
     55 * so it should not need to call the function pointer inside  
     56 * #pjmedia_transport_op directly. 
     57 * 
     58 * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport 
     59 * 
     60 * The media transport's life-cycle normally follows the following stages: 
     61 *  - application creates the media transport when it needs to establish 
     62 *    media session to remote peer. The media transport is created using 
     63 *    specific function to create that particular transport; for example, 
     64 *    for UDP media transport, it is created with #pjmedia_transport_udp_create() 
     65 *    or #pjmedia_transport_udp_create2() functions. Different media 
     66 *    transports will provide different API to create those transports. 
     67 *  - application specifies this media transport instance when creating 
     68 *    the media session (#pjmedia_session_create()). Alternatively, it 
     69 *    may create the media stream directly with #pjmedia_stream_create() 
     70 *    and specify this transport instance in the argument. (Note: media 
     71 *    session is a high-level abstraction for media communications between 
     72 *    two endpoints, and it may contain more than one media stream, for 
     73 *    example, an audio stream and a video stream). 
     74 *  - when stream is created, it will "attach" itself to the media  
     75 *    transport by calling #pjmedia_transport_attach(), which is a thin 
     76 *    wrapper which calls "attach()" method of the media transport's  
     77 *    "virtual function pointer" (#pjmedia_transport_op). Among other things, 
     78 *    the stream specifies two callback functions to be called: one 
     79 *    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 
     87 *    the media transport by calling #pjmedia_transport_detach(), which is 
     88 *    a thin wrapper which calls "detach()" method of the media transport's  
     89 *    "virtual function pointer" (#pjmedia_transport_op). After the transport 
     90 *    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 
     95 *    call #pjmedia_transport_close() function, which is thin wrapper which  
     96 *    calls "destroy()" method of the media transport's  "virtual function  
     97 *    pointer" (#pjmedia_transport_op).  
     98 * 
     99 * 
     100 * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport 
     101 * 
     102 * To implement a new type of media transport, one needs to "subclass" the 
     103 * media transport "class" (#pjmedia_transport) by providing the "methods" 
     104 * in the media transport "interface" (#pjmedia_transport_op), and provides 
     105 * a function to create this new type of transport (similar to  
     106 * #pjmedia_transport_udp_create() function). 
     107 * 
     108 * The media transport is expected to run indepently, that is there should 
     109 * be no polling like function to poll the transport for incoming RTP/RTCP 
     110 * packets. This normally can be done by registering the media sockets to 
     111 * the media endpoint's IOQueue, which allows the transport to be notified 
     112 * when incoming packet has arrived. 
     113 * 
     114 * Alternatively, media transport may utilize thread(s) internally to wait 
     115 * for incoming packets. The thread then will call the appropriate RTP or 
     116 * RTCP callback provided by its user (stream) whenever packet is received. 
     117 * If the transport's user is a stream, then the callbacks provided by the 
     118 * stream will be thread-safe, so the transport may call these callbacks 
     119 * without having to serialize the access with some mutex protection. But 
     120 * the media transport may still have to protect its internal data with 
     121 * mutex protection, since it may be called by application's thread (for 
     122 * example, to send RTP/RTCP packets). 
     123 * 
     124 * For an example of media transport implementation, please refer to  
     125 * <tt>transport_udp.h</tt> and <tt>transport_udp.c</tt> in PJMEDIA source 
     126 * distribution. 
    48127 */ 
    49128 
    … …  
    84163 
    85164    /** 
    86      * This function is called by the stream when the stream is no longer 
    87      * need the transport (normally when the stream is about to be closed). 
     165     * This function is called by the stream when the stream no longer 
     166     * needs the transport (normally when the stream is about to be closed). 
     167     * After the transport is detached, it will ignore incoming 
     168     * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets. 
     169     * Application may re-attach the media transport to another transport  
     170     * user (e.g. stream) after the transport has been detached. 
    88171     * 
    89172     * Application should call #pjmedia_transport_detach() instead of  
    … …  
    187270/** 
    188271 * Detach callbacks from the transport. 
    189  * This is just a simple wrapper which calls <tt>attach()</tt> member of  
    190  * the transport. 
     272 * This is just a simple wrapper which calls <tt>detach()</tt> member of  
     273 * the transport. After the transport is detached, it will ignore incoming 
     274 * RTP/RTCP packets, and will refuse to send outgoing RTP/RTCP packets. 
     275 * Application may re-attach the media transport to another transport user 
     276 * (e.g. stream) after the transport has been detached. 
    191277 * 
    192278 * @param tp        The media transport. 
    … …  
    203289/** 
    204290 * Send RTP packet with the specified media transport. This is just a simple 
    205  * wrapper which calls <tt>send_rtp()</tt> member of the transport. 
     291 * wrapper which calls <tt>send_rtp()</tt> member of the transport. The  
     292 * RTP packet will be delivered to the destination address specified in 
     293 * #pjmedia_transport_attach() function. 
    206294 * 
    207295 * @param tp        The media transport. 
    … …  
    221309/** 
    222310 * Send RTCP packet with the specified media transport. This is just a simple 
    223  * wrapper which calls <tt>send_rtcp()</tt> member of the transport. 
     311 * wrapper which calls <tt>send_rtcp()</tt> member of the transport. The  
     312 * RTCP packet will be delivered to the destination address specified in 
     313 * #pjmedia_transport_attach() function. 
    224314 * 
    225315 * @param tp        The media transport. 
    … …  
    239329/** 
    240330 * Close media transport. This is just a simple wrapper which calls  
    241  * <tt>destroy()</tt> member of the transport. 
     331 * <tt>destroy()</tt> member of the transport. This function will free 
     332 * all resources created by this transport (such as sockets, memory, etc.). 
    242333 * 
    243334 * @param tp        The media transport. 
Note: See TracChangeset for help on using the changeset viewer.