Changes between Version 3 and Version 4 of Media_Transport_Adapter

Timestamp:

Sep 24, 2011 8:56:26 AM (13 years ago)

Author:

bennylp

Comment:

--

Media_Transport_Adapter

@@ -16 +16 @@
 == Introduction ==
 
-'''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.
+'''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.
 
-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.
+The media transport diagram:[[BR]]
+[[Image(media-transport.png, center)]]
 
-'''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!
+See [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT.htm#details Media Transport reference documentation] for more info.
 
-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.
 
+
+'''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).
+
+One 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.
+
+From the media transport diagram above, here is the transport diagram when SRTP is used: [[BR]]
+[[Image(media-srtp-transport.png, center)]]
+
+Please see [http://www.pjsip.org/docs/latest/pjmedia/docs/html/group__PJMEDIA__TRANSPORT__SRTP.htm#details SRTP reference documentation] for more info.
 
 [[BR]]
@@ -29 +38 @@
 = Implementing Your Own Adapter =
 
-The following steps provide rough guidance to implementing your own adapter:
- - start with the transport adapter sample from pjmedia directory.
- - copy this to your application directory (you don't need to work in pjmedia directory)
- - implement the media transport operations as necessary. See the media transport reference documentation for more information.
+Implementing a new adapter should not be too difficult. The following steps provide rough guidance to implementing your own adapter:
+ - 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.
+ - 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).
+ - 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.
+ - 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. 
+   - 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.
  - integrate your adapter to your PJSUA-LIB based application (see the next section)
+
+[[BR]]
 
 = Integrating Your Adapter =
 
-The following step(s) show how to integrate your adapter so that it can be recognized by PJSUA-LIB and used for your application:
- - implement {{{on_create_media_transport()}}} callback. This callback notifies application when media transport needs to be created. 
+Integrating 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:
+ - 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.
+ - in the callback, you'd create your adapter and return it to PJSUA-LIB.
+ - once your adapter is used by a call, you will use your adapter API to instruct it to do whatever you want.
 
-Please note the following:
- - the callback is only available in version 1.12 or later.
- - 
+Please be prepared that:
+ - 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.
+ - 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.