MediaProvider and Call architecture

Applies to: Skype for Business 2015

The MediaProvider abstract class is intended to provide an abstraction of the link between the Signaling layer and Session Description Protocol (SDP) negotiation. A MediaProvider subclass facilitates offer/answer negotiation in a signaling session when an application initiates an outgoing call or accepts an incoming call. The Call abstract class is intended to provide an abstraction of a call that uses a particular media type. A Call subclass instance invokes methods on the associated MediaProvider subclass instance to get an offer or answer, or to set an answer on the associated MediaProvider subclass instance.

If your application is intended to work with media types other than the standard media types built into UCMA 5.0, message, audio, and image, you will need to create non-abstract classes that inherit from the MediaProvider and Call classes. This topic describes the how the MediaProvider and Call subclass instances must interact so that your application operates successfully.

For the remainder of this topic, any mentions of MediaProvider or Call should be understood to mean developer-implemented subclasses of the MediaProvider and Call classes.

MediaProvider and Call interaction

A developer who implements a non-abstract class such as AudioVideoMediaProvider should be aware of the following important virtual MediaProvider properties and methods. Only the most important properties and methods on MediaProvider are discussed.

Properties that define MediaProvider-supported behavior

The following table lists the MediaProvider properties that define the behavior supported by a particular MediaProvider implementation. The only property that must be implemented in a class derived from the MediaProvider class is SupportedMediaTypes. This property should return the media names supported by the class derived from MediaProvider. All other properties can be overridden as needed to support a particular capability.

Methods that handle SDP offer/answer negotiation

A key role of a class derived from the MediaProvider class is to participate in SDP offer/answer negotiation for a Call. A typical MediaProvider subclass, such as the AudioVideoProvider class, also manages the MediaFlow instance (media session) associated with the Call. This section describes the most important MediaProvider methods related to offer/answer negotiation.

Methods that control the signaling session and the media session

The abstract methods shown in the following table must be implemented in a class derived from the MediaProvider class. These methods are used to terminate the signaling session, which is associated with signaling information and instant message text, and the media session, which is associated with audio.

Successful outgoing SDP negotiation or renegotiation

The scenario described here is one in which SDP negotiation is successful. This scenario begins when the Call instance starts a new outgoing SDP negotiation or renegotiation.

1. The MediaProvider instance starts the asynchronous process of generating a new SDP offer by calling its BeginGetOffer method.

2. When the SDP offer is ready, the MediaProvider instance completes the asynchronous operation by invoking the callback method represented by the BeginGetOffer method’s AsyncCallback parameter.

3. The Call instance invokes EndGetOffer and expects the MediaProvider instance to return the SDP offer.

4. When the Call instance receives the SDP offer from the remote end, it calls the MediaProvider’s SetOffer method.

5. For a new Call instance, the application calls BeginEstablish on the Call instance to start an outgoing SDP renegotiation. This is the typical scenario.

   For a Call instance that is already established, the MediaProvider instance calls its BeginSdpRenegotiation method.

For information about error cases and declining an incoming negotiation request, see Negotiating declined offers.

Successful incoming SDP renegotiation

This scenario describes the steps involved in handling an incoming SDP renegotiation.

1. The MediaProvider instance starts an asynchronous operation to generate the SDP answer by calling its BeginGetAnswer method.

2. When the SDP answer is ready, the MediaProvider instance invokes the callback method represented by the BeginGetAnswer method’s AsyncCallback parameter.

3. The Call instance invokes EndGetAnswer and expects the MediaProvider instance to return the SDP answer. The SdpAnswer object returned by EndGetOffer is used in response to an incoming negotiation request.

Whenever a MediaProvider subclass object, such as an AudioVideoMediaProvider instance, intends to renegotiate SDP, it calls the BeginSdpRenegotiation(CallDialogContext, AsyncCallback, Object) method to notify the associated non-abstract Call subclass instance to start SDP renegotiation. Any collision of renegotiation is handled by the Call instance.

Whenever the Call object receives a message in an existing session and the message is not to the Call object itself, the message is delivered to the MediaProvider instance by a call to HandleMessageReceived(MessageReceivedEventArgs). If the MediaProvider instance takes no action on the message, it is forwarded to the application. If a delegate for the application also takes no action on the message, the Call instance rejects the message. The AudioVideoProvider and InstantMessagingProvider implementations are internal, but are tied into the platform architecture as described in the following diagram.

In addition to simple SDP negotiation for simple two-party calls, the MediaProvider instance also provides a mechanism for escalating a two-party call to multiparty conferencing. For information about escalating a two-party call to a conference, see Escalating to a Conference.

SdpContentDescription and offer/answer

The constructors for the SdpOffer and SdpAnswer classes all have parameters of type SdpContentDescription, a class that inherits from the ContentDescription class. The ContentDescription class contains the ContentType property and a GetBody() method, which returns the content body. An important distinction between SdpOffer and SdpAnswer is that an SdpOffer instance can contain multiple SDP offers, while an SdpAnswer instance can contain only one SDP answer.

An SdpOffer instance contains a list of offers (the Offers property) that have been received or are being sent out.

Incoming offers can be accepted as multiple offers in a multipart/mime message body or as a single offer in message with SDP content type. If SDP offers are present within the multipart/mime section, the Call instance extracts them from the multipart/mime content and presents the list to the MediaProvider instance. If the offer’s ContentType is "sdp" there should be only one offer in the Offers list. The MessageHeaders property on the SdpOffer instance should contain a list of incoming headers received on the offer.

For an outgoing offer, if there is only one offer in the list, the offer should be sent out with ContentType set to "sdp"; otherwise a multipart/mime offer should be created from the list of offers. The MessageHeaders property on the SdpOffer instance should contain the list of additional SIP headers that will be included as message headers with the offer message.

For an outgoing answer, the Answer property on the SdpAnswer instance represents the answer that has been received. The MessageHeaders property on the SdpAnswer instance contains the list of additional SIP headers that the MediaProvider instance needs to send out with the answer.

The following figure illustrates the relationship between SdpAnswer, SdpOffer, and SdpContentDescription objects.

This section includes the following topics:

• Negotiating declined offers
• Triggering SDP renegotiations
• Call forking with early media
• Error handling