Media Transport Adapter

Table of Contents

1. Introduction
2. Implementing Your Own Adapter
3. Integrating Your Adapter
4. Examples

This article describes the media transport adapter and how to implement and integrate your custom adapter to your application. Media Transport Adapter is the primary mean to integrate RTP/RTCP processing into the media flow, get full access to SDP, and be involved in SDP negotiation.

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 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 diagram:

See ​Media Transport reference documentation for more info.

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:

Please see ​SRTP reference documentation for more info.

Implementing Your Own Adapter

Implementing a new adapter should not be too difficult. The following steps provide rough guidance to implementing your own adapter:

• see the ​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., ​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)

Integrating Your Adapter

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 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.

Examples

The pjsua application contains sample code to create and integrate the sample media transport adapter. Open the pjsua_app.c source, and look for TRANSPORT_ADAPTER_SAMPLE macro.