![(please configure the [header_logo] section in trac.ini)](/repos/chrome/site/pj.jpg)
Changeset 2037 for pjproject/trunk/pjmedia/include/pjmedia/transport.h
- Timestamp:
- Jun 20, 2008 9:39:02 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/trunk/pjmedia/include/pjmedia/transport.h
r2032 r2037 30 30 31 31 /** 32 * @defgroup PJMEDIA_TRANSPORT Media Transports 33 * @ingroup PJMEDIA 32 * @defgroup PJMEDIA_TRANSPORT Media Transport 34 33 * @brief Transports. 35 * Transport related components.36 */37 38 /**39 * @defgroup PJMEDIA_TRANSPORT_H Media Network Transport Interface40 * @ingroup PJMEDIA_TRANSPORT41 * @brief PJMEDIA object for sending/receiving media packets over the network42 34 * @{ 43 35 * The media transport (#pjmedia_transport) is the object to send and 44 36 * receive media packets over the network. The media transport interface 45 37 * allows the library to be extended to support different types of 46 * transports to send and receive packets. Currently only the standard 47 * UDP transport implementation is provided (see \ref PJMEDIA_TRANSPORT_UDP), 48 * but application designer may extend the library to support other types 49 * of custom transports such as RTP/RTCP over TCP, RTP/RTCP over HTTP, etc. 38 * transports to send and receive packets. 50 39 * 51 40 * The media transport is declared as #pjmedia_transport "class", which … … 63 52 64 53 65 * \section PJMEDIA_TRANSPORT_H_USING Using the Media Transport54 * \section PJMEDIA_TRANSPORT_H_USING Basic Media Transport Usage 66 55 * 67 56 * The media transport's life-cycle normally follows the following stages. … … 142 131 * 143 132 * 144 * \section PJMEDIA_TRANSPORT_H_EXT Media Transport Extended API133 * \section offer_answer Interaction with SDP Offer/Answer 145 134 146 Apart from the basic interface above, the media transport provides some 147 more APIs: 148 149 - pjmedia_transport_media_create() 150 \n 151 This API is provided to allow the media transport to add more information 152 in the SDP offer, before the offer is sent to remote. Additionally, for 153 answerer side, this callback allows the media transport to reject the 154 offer before this offer is processed by the SDP negotiator. 155 156 - pjmedia_transport_media_start() 157 \n 158 This API should be called after offer and answer are negotiated, and 159 both SDPs are available, and before the media is started. For answerer 160 side, this callback will be called before the answer is sent to remote, 161 to allow media transport to put additional info in the SDP. For 162 offerer side, this callback will be called after SDP answer is 163 received. In this callback, the media transport has the final chance 164 to negotiate/validate the offer and answer before media is really 165 started (and answer is sent, for answerer side). 166 167 - pjmedia_transport_media_stop() 168 \n 169 This API should be called when the media is stopped, to allow the media 170 transport to release its resources. 171 172 - pjmedia_transport_simulate_lost() 173 \n 174 This API can be used to instruct media transport to simulate packet lost 175 on a particular direction. 135 For basic UDP transport, the \ref PJMEDIA_TRANSPORT_H_USING above is 136 sufficient to use the media transport. However, more complex media 137 transports such as \ref PJMEDIA_TRANSPORT_SRTP and \ref 138 PJMEDIA_TRANSPORT_ICE requires closer interactions with SDP offer and 139 answer negotiation. 140 141 The media transports can interact with the SDP offer/answer via 142 these APIs: 143 - #pjmedia_transport_media_create(), to initialize the media transport 144 for new media session, 145 - #pjmedia_transport_encode_sdp(), to encode SDP offer or answer, 146 - #pjmedia_transport_media_start(), to activate the settings that 147 have been negotiated by SDP offer answer, and 148 - #pjmedia_transport_media_stop(), to deinitialize the media transport 149 and reset the transport to its idle state. 150 151 The usage of these API in the context of SDP offer answer will be 152 described below. 153 154 \subsection media_create Initializing Transport for New Session 155 156 Application must call #pjmedia_transport_media_create() before using 157 the transport for a new session. 158 159 \subsection creat_oa Creating SDP Offer and Answer 160 161 The #pjmedia_transport_encode_sdp() is used to put additional information 162 from the transport to the local SDP, before the SDP is sent and negotiated 163 with remote SDP. 164 165 When creating an offer, call #pjmedia_transport_encode_sdp() with 166 local SDP (and NULL as \a rem_sdp). The media transport will add the 167 relevant attributes in the local SDP. Application then gives the local 168 SDP to the invite session to be sent to remote agent. 169 170 When creating an answer, also call #pjmedia_transport_encode_sdp(), 171 but this time specify both local and remote SDP to the function. The 172 media transport will once again modify the local SDP and add relevant 173 attributes to the local SDP, if the appropriate attributes related to 174 the transport functionality are present in remote offer. The remote 175 SDP does not contain the relevant attributes, then the specific transport 176 functionality will not be activated for the session. 177 178 The #pjmedia_transport_encode_sdp() should also be called when application 179 sends subsequent SDP offer or answer. The media transport will encode 180 the appropriate attributes based on the state of the session. 181 182 \subsection media_start Offer/Answer Completion 183 184 Once both local and remote SDP have been negotiated by the 185 \ref PJMEDIA_SDP_NEG (normally this is part of PJSIP invite session), 186 application should give both local and remote SDP to 187 #pjmedia_transport_media_start() so that the settings are activated 188 for the session. This function should be called for both initial and 189 subsequent SDP negotiation. 190 191 \subsection media_stop Stopping Transport 192 193 Once session is stop application must call #pjmedia_transport_media_stop() 194 to deactivate the transport feature. Application may reuse the transport 195 for subsequent media session by repeating the #pjmedia_transport_media_create(), 196 #pjmedia_transport_encode_sdp(), #pjmedia_transport_media_start(), and 197 #pjmedia_transport_media_stop() above. 176 198 177 199 * \section PJMEDIA_TRANSPORT_H_IMPL Implementing Media Transport … … 199 221 * example, to send RTP/RTCP packets). 200 222 * 201 * For an example of media transport implementation, please refer to202 * <tt>transport_udp.h</tt> and <tt>transport_udp.c</tt> in PJMEDIA source 203 * distribution. 204 */ 223 */ 224 225 226 #include <pjmedia/sdp.h> 205 227 206 228 PJ_BEGIN_DECL 207 208 #include <pjmedia/sdp.h>209 229 210 230 … … 347 367 /** 348 368 * This function is called by application to start the transport 349 * based on SDP negotiation result.369 * based on local and remote SDP. 350 370 * 351 371 * Application should call #pjmedia_transport_media_start() instead of … … 414 434 415 435 /** 416 * This structure declares stream transport. A streamtransport is called436 * This structure declares media transport. A media transport is called 417 437 * by the stream to transmit a packet, and will notify stream when 418 438 * incoming packet is arrived. … … 638 658 639 659 /** 640 * Prepare the media transport for a new media session, and optionally 641 * encode the relevant information in the \a sdp_local. Application must 660 * Prepare the media transport for a new media session, Application must 642 661 * call this function before starting a new media session using this 643 662 * transport. … … 649 668 * @param sdp_pool Pool object to allocate memory related to SDP 650 669 * messaging components. 651 * @param option Option flags, from #pjmedia_tranport_media_option 652 * @param rem_sdp Remote SDP if it's available. 670 * @param options Option flags, from #pjmedia_tranport_media_option 671 * @param rem_sdp Remote SDP if local SDP is an answer, otherwise 672 * specify NULL if SDP is an offer. 653 673 * @param media_index Media index in SDP. 654 674 * … … 668 688 /** 669 689 * Put transport specific information into the SDP. This function can be 670 * called to create SDP offer or answer, depending whether \a rem_sdp671 * parameter is present.690 * called to put transport specific information in the initial or 691 * subsequent SDP offer or answer. 672 692 * 673 693 * This is just a simple wrapper which calls <tt>encode_sdp()</tt> member … … 679 699 * @param sdp The local SDP to be filled in information from the 680 700 * media transport. 681 * @param rem_sdp Remote SDP if it's available. 701 * @param rem_sdp Remote SDP if local SDP is an answer, otherwise 702 * specify NULL if SDP is an offer. 682 703 * @param media_index Media index in SDP. 683 704 * … … 695 716 696 717 /** 697 * Start the transport with regards to SDP negotiation result. 698 * This API should be called after offer and answer are negotiated, and 699 * both SDPs are available, and before the media is started. For answerer 700 * side, this callback will be called before the answer is sent to remote, 701 * to allow media transport to put additional info in the SDP. For 702 * offerer side, this callback will be called after SDP answer is 703 * received. In this callback, the media transport has the final chance 704 * to negotiate/validate the offer and answer before media is really 705 * started (and answer is sent, for answerer side). 718 * Start the transport session with the settings in both local and remote 719 * SDP. The actual work that is done by this function depends on the 720 * underlying transport type. For SRTP, this will activate the encryption 721 * and decryption based on the keys found the SDPs. For ICE, this will 722 * start ICE negotiation according to the information found in the SDPs. 706 723 * 707 724 * This is just a simple wrapper which calls <tt>media_start()</tt> member … … 710 727 * @param tp The media transport. 711 728 * @param tmp_pool The memory pool for allocating temporary objects. 712 * @param option The media transport option.713 729 * @param sdp_local Local SDP. 714 730 * @param sdp_remote Remote SDP. 715 * @param media_index Media index to start.731 * @param media_index Media index in the SDP. 716 732 * 717 733 * @return PJ_SUCCESS on success, or the appropriate error code. … … 729 745 730 746 /** 731 * Stop the transport. 732 * This API should be called when the media is stopped, to allow the media 733 * transport to release its resources. 747 * This API should be called when the session is stopped, to allow the media 748 * transport to release its resources used for the session. 734 749 * 735 750 * This is just a simple wrapper which calls <tt>media_stop()</tt> member
Note: See TracChangeset
for help on using the changeset viewer.
