Changes between Version 3 and Version 4 of Media_Transport_Adapter


Ignore:
Timestamp:
Sep 24, 2011 8:56:26 AM (8 years ago)
Author:
bennylp
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • Media_Transport_Adapter

    v3 v4  
    1616== Introduction == 
    1717 
    18 '''Media transport''' is an object to connect the media application to the network. The most obvious tasks of the media transport are of course to send and receive RTP and RTCP packets. But media transports task can be more than that; the ICE media transport, for example, also takes care of NAT traversal, while the SRTP transport secures your media communication. See [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm Media Transport reference documentation] for more info. 
     18'''Media transport''' is an object to connect the media application to the network. The most obvious tasks of the media transport are of course to send and receive RTP and RTCP packets. But media transports can do more than that; the ICE media transport, for example, also takes care of NAT traversal, while the SRTP transport secures your media communication. The media transport also has access to SDP during SDP negotiation; it has access to both local and remote offer and answer, and may add or modify local SDP offer or answer (but note that this feature is only available if PJSUA-LIB is used at the higher level). Hence the media transport API in PJMEDIA provides rich and fully featured framework to integrate transport feature into the rest of the media framework. 
    1919 
    20 The media transport also has access to SDP during SDP negotiation; it has access to both local and remote offer and answer, and may add or modify local SDP offer or answer. But note that this feature is only available if PJSUA-LIB is used at the higher level. 
     20The media transport diagram:[[BR]] 
     21[[Image(media-transport.png, center)]] 
    2122 
    22 '''Media transport adapter''' is a variant of media transport, where instead of transmitting and receiving packets directly to/from the network, it uses another media transport to do that. The adapter is installed between the media stream object and another transport adapter, and have full access to the RTP/RTCP packets that are exchanged between the two. The adapter may even inject it's own packets to either direction if it wants to, or drop them. Because of this arrangement, the obvious use of the adapter is to add processing to the media packets without having to be burdened with the actual management of the network. Once the adapter is implemented, it will immediately be able to take advantage of existing and future media transports in PJMEDIA, such as UDP and ICE media transports, including other transport adapters! 
     23See [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm#details Media Transport reference documentation] for more info. 
    2324 
    24 The SRTP support is implemented as a media transport adapter. Apart from the actual encoding and decoding of packets, it also reads and writes the SDP session descriptor, and the mechanism provided by the media transport API is capable to support this. 
    2525 
     26 
     27'''Media transport adapter''' is a variant of media transport, where instead of interfacing directly to the network, it uses another media transport to do that. The adapter is installed between the media stream object and another transport, and have full access to RTP/RTCP packets that are exchanged between them. The adapter may inject it's own packets to either direction if it wants to, or even drop some of them. The main use of the adapter is to add processing to the media packets while reusing existing transport features (such as ICE). 
     28 
     29One main example of transport adapter is the SRTP transport. It provides encryption and decryption of RTP and RTCP packets, and it also fully interacts with the SDP negotiation, all using the media transport framework. 
     30 
     31From the media transport diagram above, here is the transport diagram when SRTP is used: [[BR]] 
     32[[Image(media-srtp-transport.png, center)]] 
     33 
     34Please see [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT__SRTP.htm#details SRTP reference documentation] for more info. 
    2635 
    2736[[BR]] 
     
    2938= Implementing Your Own Adapter = 
    3039 
    31 The following steps provide rough guidance to implementing your own adapter: 
    32  - start with the transport adapter sample from pjmedia directory. 
    33  - copy this to your application directory (you don't need to work in pjmedia directory) 
    34  - implement the media transport operations as necessary. See the media transport reference documentation for more information. 
     40Implementing a new adapter should not be too difficult. The following steps provide rough guidance to implementing your own adapter: 
     41 - see the [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm#details reference documentation] again to understand how the media transport will be operated by pjsip. If your media transport needs to interact with SDP, then make sure you read and understand the ''Interaction with SDP Offer/Answer'' section in the documentation. 
     42 - next, start with the transport adapter sample from pjmedia directory. Copy this to your application directory (you don't need to add the transport to pjmedia directory). 
     43 - implement the media transport methods (i.e., [http://www.pjsip.org/docs/latest/pjmedia/docs/html/structpjmedia__transport__op.htm pjmedia_transport_op]) as necessary. At the very minimum, you'd need to implement: ''get_info()'', ''attach()'', ''detach()'', ''send_rtp()'', ''send_rtcp2()'', and ''destroy()''. You'll need to implement more if the adapter needs to interact with SDP. Again, the info is provided in the reference documentation. 
     44 - Apart from the transport methods above, you also most likely need to equip the adapter with additional APIs according to your application requirement. At the very least, you'd need an API to create the transport itself, as this API is not part of the framework (it is you who will call this create function, not pjsip), as has the adapter sample.  
     45   - As an example, suppose you are creating a transport adapter that randomly duplicates packet; then you'd need to equip your adapter with function/API to control how much duplication will be injected by your adapter. 
    3546 - integrate your adapter to your PJSUA-LIB based application (see the next section) 
     47 
     48[[BR]] 
    3649 
    3750= Integrating Your Adapter = 
    3851 
    39 The following step(s) show how to integrate your adapter so that it can be recognized by PJSUA-LIB and used for your application: 
    40  - implement {{{on_create_media_transport()}}} callback. This callback notifies application when media transport needs to be created.  
     52Integrating a media transport adapter has become easier since pjsip version 1.12 with the addition of a new {{{on_create_media_transport()}}} callback (see ticket #1173 for more info). The following steps show how to integrate your adapter: 
     53 - implement {{{on_create_media_transport()}}} callback. This callback notifies application when media transport needs to be created, and this is where you supply your adapter to be used by PJSUA-LIB. See the description in ticket #1173 on how the callback is to be used. 
     54 - in the callback, you'd create your adapter and return it to PJSUA-LIB. 
     55 - once your adapter is used by a call, you will use your adapter API to instruct it to do whatever you want. 
    4156 
    42 Please note the following: 
    43  - the callback is only available in version 1.12 or later. 
    44  -  
     57Please be prepared that: 
     58 - during a call, ''attach()'' and ''detach()'' operation may be called more than once, e.g. when the media is restarted e.g. due to call hold. 
     59 - your transport may be destroyed while the call is running, and/or the {{{on_create_media_transport()}}} callback is called again for the same call. You cannot assume that {{{on_create_media_transport()}}} callback is only called once for a call. These happen when media is removed or added for a call. 
    4560 
    4661