net.java.sip.communicator.impl.protocol.jabber.jinglesdp
Class JingleUtils

java.lang.Object
  net.java.sip.communicator.impl.protocol.jabber.jinglesdp.JingleUtils

public class JingleUtils
extends Object

The class contains a number of utility methods that are meant to facilitate creating and parsing jingle media rtp description descriptions and transports.

Author:

Emil Ivov, Lyubomir Marinov

Constructor Summary

JingleUtils()

Method Summary

static ContentPacketExtension	createDescription(ContentPacketExtension.CreatorEnum creator, String contentName, ContentPacketExtension.SendersEnum senders, List<MediaFormat> formats, List<RTPExtension> rtpExtensions, DynamicPayloadTypeRegistry dynamicPayloadTypes, DynamicRTPExtensionsRegistry rtpExtensionsRegistry) Creates a new ContentPacketExtension instance according to the specified formats, connector and direction, and using the dynamicPayloadTypes registry to handle dynamic payload type registrations.
static MediaStreamTarget	extractDefaultTarget(ContentPacketExtension content) Returns the default candidate for the specified content content.
static List<MediaFormat>	extractFormats(RtpDescriptionPacketExtension description, DynamicPayloadTypeRegistry ptRegistry) Extracts and returns the list of MediaFormats advertised in description preserving their oder and registering dynamic payload type numbers in the specified ptRegistry.
static List<RTPExtension>	extractRTPExtensions(RtpDescriptionPacketExtension desc, DynamicRTPExtensionsRegistry extMap) Extracts and returns the list of RTPExtensions advertised in desc and registers newly encountered ones into the specified extMap.
static PayloadTypePacketExtension	formatToPayloadType(MediaFormat format, DynamicPayloadTypeRegistry ptRegistry) Converts a specific MediaFormat into a new PayloadTypePacketExtension instance.
static MediaDirection	getDirection(ContentPacketExtension.SendersEnum senders, boolean initiatorPerspective) Determines the direction of the media stream that content describes and returns the corresponding MediaDirection enum entry.
static MediaDirection	getDirection(ContentPacketExtension content, boolean initiatorPerspective) Determines the direction of the media stream that content describes and returns the corresponding MediaDirection enum entry.
static CandidatePacketExtension	getFirstCandidate(ContentPacketExtension content, int componentID) Returns the first candidate for the specified componentID or null if no such component exists.
static RtpDescriptionPacketExtension	getRtpDescription(ContentPacketExtension content) Extracts and returns an RtpDescriptionPacketExtension provided with content or null if there is none.
static ContentPacketExtension.SendersEnum	getSenders(MediaDirection direction, boolean initiatorPerspective) Converts the specified media direction into the corresponding ContentPacketExtension.SendersEnum value so that we could add it to a content element.
static MediaFormat	payloadTypeToMediaFormat(PayloadTypePacketExtension payloadType, DynamicPayloadTypeRegistry ptRegistry) Returns the MediaFormat described in the payloadType extension or null if we don't recognize the format.
static MediaFormat	payloadTypeToMediaFormat(PayloadTypePacketExtension payloadType, MediaService mediaService, DynamicPayloadTypeRegistry ptRegistry) Returns the MediaFormat described in the payloadType extension or null if we don't recognize the format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

JingleUtils

public JingleUtils()

Method Detail

getRtpDescription

public static RtpDescriptionPacketExtension getRtpDescription(ContentPacketExtension content)

Extracts and returns an RtpDescriptionPacketExtension provided with content or null if there is none.

Parameters:

content - the media content that we'd like to extract the RtpDescriptionPacketExtension from.

Returns:

an RtpDescriptionPacketExtension provided with content or null if there is none.

extractFormats

public static List<MediaFormat> extractFormats(RtpDescriptionPacketExtension description,
                                               DynamicPayloadTypeRegistry ptRegistry)

Extracts and returns the list of MediaFormats advertised in description preserving their oder and registering dynamic payload type numbers in the specified ptRegistry. Note that this method would only include in the result list MediaFormat instances that are currently supported by our MediaService implementation and enabled in its configuration. This means that the method could return an empty list even if there were actually some formats in the mediaDesc if we support none of them or if all these we support are not enabled in the MediaService configuration form.

Parameters:

description - the MediaDescription that we'd like to probe for a list of MediaFormats

ptRegistry - a reference to the DynamycPayloadTypeRegistry where we should be registering newly added payload type number to format mappings.

Returns:

an ordered list of MediaFormats that are both advertised in the description and supported by our MediaService implementation.

payloadTypeToMediaFormat

public static MediaFormat payloadTypeToMediaFormat(PayloadTypePacketExtension payloadType,
                                                   DynamicPayloadTypeRegistry ptRegistry)

Returns the MediaFormat described in the payloadType extension or null if we don't recognize the format.

Parameters:

payloadType - the PayloadTypePacketExtension which is to be parsed into a MediaFormat.

ptRegistry - the DynamicPayloadTypeRegistry that we would use for the registration of possible dynamic payload types or null the returned MediaFormat is to not be registered into a DynamicPayloadTypeRegistry.

Returns:

the MediaFormat described in the payloadType extension or null if we don't recognize the format.

payloadTypeToMediaFormat

public static MediaFormat payloadTypeToMediaFormat(PayloadTypePacketExtension payloadType,
                                                   MediaService mediaService,
                                                   DynamicPayloadTypeRegistry ptRegistry)

Returns the MediaFormat described in the payloadType extension or null if we don't recognize the format.

Parameters:

payloadType - the PayloadTypePacketExtension which is to be parsed into a MediaFormat.

mediaService - the MediaService implementation which is to be used for MediaFormat-related factory methods

ptRegistry - the DynamicPayloadTypeRegistry that we would use for the registration of possible dynamic payload types or null the returned MediaFormat is to not be registered into a DynamicPayloadTypeRegistry.

Returns:

the MediaFormat described in the payloadType extension or null if we don't recognize the format.

extractRTPExtensions

public static List<RTPExtension> extractRTPExtensions(RtpDescriptionPacketExtension desc,
                                                      DynamicRTPExtensionsRegistry extMap)

Extracts and returns the list of RTPExtensions advertised in desc and registers newly encountered ones into the specified extMap. The method returns an empty list in case there were no extmap advertisements in desc.

Parameters:

desc - the RtpDescriptionPacketExtension that we'd like to probe for a list of RTPExtensions

extMap - a reference to the DynamycRTPExtensionsRegistry where we should be registering newly added extension mappings.

Returns:

a List of RTPExtensions advertised in the mediaDesc description.

getSenders

public static ContentPacketExtension.SendersEnum getSenders(MediaDirection direction,
                                                            boolean initiatorPerspective)

Converts the specified media direction into the corresponding ContentPacketExtension.SendersEnum value so that we could add it to a content element. The initiatorPerspectice allows callers to specify whether the direction is to be considered from the session initator's perspective or that of the responder.

Example: A MediaDirection.SENDONLY value would be translated to ContentPacketExtension.SendersEnum.initiator from the initiator's perspective and to ContentPacketExtension.SendersEnum.responder otherwise.

Parameters:

direction - the MediaDirection that we'd like to translate.

initiatorPerspective - true if the direction param is to be considered from the initiator's perspective and false otherwise.

Returns:

one of the MediaDirection values indicating the direction of the media steam described by content.

getDirection

public static MediaDirection getDirection(ContentPacketExtension content,
                                          boolean initiatorPerspective)

Determines the direction of the media stream that content describes and returns the corresponding MediaDirection enum entry. The method looks for a direction specifier attribute (i.e. the content 'senders' attribute) or the absence thereof and returns the corresponding MediaDirection entry. The initiatorPerspectice allows callers to specify whether the direction is to be considered from the session initiator's perspective or that of the responder.

Example: An initiator value would be translated to MediaDirection.SENDONLY from the initiator's perspective and to MediaDirection.RECVONLY from the responder's.

Parameters:

content - the description of the media stream whose direction we are trying to determine.

initiatorPerspective - true if the senders argument is to be translated into a direction from the initiator's perspective and false for the sender's.

Returns:

one of the MediaDirection values indicating the direction of the media steam described by content.

getDirection

public static MediaDirection getDirection(ContentPacketExtension.SendersEnum senders,
                                          boolean initiatorPerspective)

Determines the direction of the media stream that content describes and returns the corresponding MediaDirection enum entry. The method looks for a direction specifier attribute (i.e. the content 'senders' attribute) or the absence thereof and returns the corresponding MediaDirection entry. The initiatorPerspectice allows callers to specify whether the direction is to be considered from the session initiator's perspective or that of the responder.

Parameters:

senders - senders direction

initiatorPerspective - true if the senders argument is to be translated into a direction from the initiator's perspective and false for the sender's.

Returns:

one of the MediaDirection values indicating the direction of the media steam described by content.

extractDefaultTarget

public static MediaStreamTarget extractDefaultTarget(ContentPacketExtension content)

Returns the default candidate for the specified content content. The method is used when establishing new calls and we need a default candidate to initiate our stream with before we've discovered the one that ICE would pick.

Parameters:

content - the stream whose default candidate we are looking for.

Returns:

a MediaStreamTarget containing the default candidates for the stream described in content or null, if for some reason, the packet does not contain any candidates.

getFirstCandidate

public static CandidatePacketExtension getFirstCandidate(ContentPacketExtension content,
                                                         int componentID)

Returns the first candidate for the specified componentID or null if no such component exists.

Parameters:

content - the ContentPacketExtension that we'll be searching for a component.

componentID - the id of the component that we are looking for (e.g. 1 for RTP, 2 for RTCP);

Returns:

the first candidate for the specified componentID or null if no such component exists.

createDescription

public static ContentPacketExtension createDescription(ContentPacketExtension.CreatorEnum creator,
                                                       String contentName,
                                                       ContentPacketExtension.SendersEnum senders,
                                                       List<MediaFormat> formats,
                                                       List<RTPExtension> rtpExtensions,
                                                       DynamicPayloadTypeRegistry dynamicPayloadTypes,
                                                       DynamicRTPExtensionsRegistry rtpExtensionsRegistry)

Creates a new ContentPacketExtension instance according to the specified formats, connector and direction, and using the dynamicPayloadTypes registry to handle dynamic payload type registrations. The type (e.g. audio/video) of the media description is determined via from the type of the first MediaFormat in the formats list.

Parameters:

creator - indicates whether the person who originally created this content was the initiator or the responder of the jingle session

contentName - the name of the content element as indicator by the creator or, in case we are the creators: as we'd like it to be.

formats - the list of formats that should be advertised in the newly created content extension.

senders - indicates the direction of the media in this stream.

rtpExtensions - a list of RTPExtensions supported by the MediaDevice that we will be advertising.

dynamicPayloadTypes - a reference to the DynamicPayloadTypeRegistry that we should be using to lookup and register dynamic RTP mappings.

rtpExtensionsRegistry - a reference to the DynamicRTPExtensionRegistry that we should be using to lookup and register URN to ID mappings.

Returns:

the newly create SDP MediaDescription.

formatToPayloadType

public static PayloadTypePacketExtension formatToPayloadType(MediaFormat format,
                                                             DynamicPayloadTypeRegistry ptRegistry)

Converts a specific MediaFormat into a new PayloadTypePacketExtension instance.

Parameters:

format - the MediaFormat we'd like to convert.

ptRegistry - the DynamicPayloadTypeRegistry to use for formats that don't have a static pt number.

Returns:

the new PayloadTypePacketExtension which contains format's parameters.