Download:

MessageManipulatorExample .zip

This article covers the basic knowledge about SDP (Session Description Protocol) in connection with Ozeki VoIP SIP SDK support and softphone building. After reading this material, you will have all the information about SDP and the way Ozeki VoIP SIP SDK uses it.

Figure 1 - VoIP SDP calls

Introduction

The Session Description Protocol (SDP) is a format for describing streaming media initialization parameters. SDP is intended for describing multimedia communication sessions for the purposes of session announcement, session invitation, and parameter negotiation.
Figure 2 shows a possible PDU for an SIP invite call with SDP package.

Figure 2 - PDU for a SIP INVITE call with SDP package

SDP does not deliver media itself but is used for negotiation between end points of media type, format, and all associated properties. The set of properties and parameters are often called a session profile. SDP is designed to be extensible to support new media types and formats.

The session, time and media are defined with some field information (each is a line) some of which are optional. Table 1 shows the fields for Session description. The order of the fields has to be the same as in the table.

Table 1 - Session description fields for SDP

Session description contains two other description types, time and media description. The time description field is required to occur at least one time with a specific field and can occur in more lines with one of the fields shown in Table 2.

Table 2 - Time descriptor fields for SDP

The session description can also contain media description fields that are shown in Table 3. It is not required to add media description, but if you add one, the m field is required to add to each media description.

Table 3 - Media description fields for SDP

The whole standard for SDP is written in RFC 4566 standard documentation.

Now you are familiar with all the possible parameterization of the SDP. Let's see how it is coded in Ozeki VoIP SIP SDK.

How Ozeki VoIP SIP SDK handles SDP

From this point the article will describe some of the Ozeki VoIP SIP SDK built-in namespaces, classes and methods that handle SDP. If you want to properly follow the article, you will need to have Ozeki VoIP SIP SDK installed on your computer.

Ozeki VoIP SIP SDK provides a great support for SDP. There is a set of namespaces that are for SDP handling and setting the above mentioned field so you will not have to do it yourself.

When you are building your softphone application, you won't need to set SDP fields yourself as the Ozeki VoIP SIP SDK does all these settings in the background. However, you might be interested in the basic classes that perform this task for you.

Ozeki.VoIP.SDP namespace for the basic parsing methods

The basic namespace for supporting SDP in Ozeki VoIP SIP SDK is the Ozeki.VoIP.SDP. This namespace only contains an abstract generic class called LLParser.

The LLParser<T> class is a representation of a parser that is for separating and identifying the SDP field information of a SIP package. It defines a lot of information fields that are for notifying the program about some events or for storing field data.

The LLParser class also defines some helping methods for parsing an incoming string that contains the dataflow of the session field information.

Ozeki.VoIP.SDP.Exceptions namespace for handling field problems

This namespace is for handling SDP exceptions. It contains three classes for parsing exceptions, parsing rule exceptions and for semantical exceptions.

A rule exception occurs when a required field is missing from the SDP flow or when the order of the fields is not proper. A semantical exception occurs when some of the field data are mistyped or wrong.

Ozeki.VoIP.SDP.Message namespace for establishing the standard

Ozeki.VoIP.SDP.Message namespace contains two classes. One for the SDP message itself and one that defines the RFC 4566 standard that defines SDP in the first place. These classes are for establishing the basic knowledge about SDP messages and these are the etalon definitions for SDP.

The SDPMessage class has the main fields for storing standards SDP session description fields. The data types of these fields are classed defined in the Ozeki.VoIP.SDP.Message.SDPFields and Ozeki.VoIP.SDP.Message.SDPData namespaces.

Ozeki.VoIP.SDP.Message.SDPData namespace for handling basic SDP data

This namspace contains the basic data concerning SDP. Three Enum types in Ozeki.VoIP.SDP.Message.SDPData represent the address type (AddressType), the bandwidth type (BandwithType) and the net type (NetType).

The concrete values for these Enum types are IP4 and IP6 for AddressType that represent the IPv4 and IPv6 standard. The BandwithType values are AS that stands for an application specific bandwidth limit, and CT that is for bandwidth limit specified by the session itself. The NetType Enum is limited to Internet at this time.

The classes in Ozeki.VoIP.SDP.Message.SDPData namespace are the following:

• Origin that represents the required 'o' field of the session
  It contains fields for address type, network type, session ID, session version, uri and username of the session

• SDPConnectionAddress represents the address of the connection

• SDPMediaDescription represents the optional media description fields
  It contains fields that are instances of classes in Ozeki.VoIP.SDP.Message.SDPFields namespace, each represents a media description field described in Table 3.

• SDPTimeData that represents the time description and zone information of the session.
  It contains two fields, one for the time description fields that is a generic Collection of SDPTime of Ozeki.VoIP.SDP.Message.SDPFields namespace objects, these are for the fields shown in Table 2 above. The other field is for the 'z' field of the session description.

• TimeUnit that is an Enum type of Ozeki.VoIP.SDP.Message.SDPData containing Day, Hour, Minute, Second and None values.

• TypedTime that is for manually given time data

• ZoneAdjustment that is the class representing the 'z' field in Table 1. The ZoneAdjustment field in SDPTimeData class is an instance of this class.

Ozeki.VoIP.SDP.Message.SDPFields namespace for working with SDP field types

This namespace contains the classes for SDP field types. It is essential to be able to define the types of the field. This method is mainly used for better identification of the given tools. It is always easier to check if an object is an instance of a class than checking it for all possible values.

Three Enum types are defined in this class. These are KeyMethod, SDPAttribute and MediaType. The KeyMethod contains the values of Base64, Clear, Prompt and Uri. As for the MediaTransportProtocol, the SDK gives the choices of RtpAvp, RtpSavp, TcpRtp and Udp. The MediaType can have the values of Application, Audio, Message, Text and Video.

The classes in Ozeki.VoIP.SDP.Message.SDPFields namespace represent the field types for the session description fields. These classes are the following:

• SDPAttribute that stores the attribute name and value of the fields

• SDPBandwith that stores the bandwidth type and the actual bandwidth value

• SDPConnection that stores the address type, the connection address and the net type

• SDPEmail that stores the email description, the domain and the username of the email box

• SDPField is an abstract class for SDP fields

• SDPInformation that stands the 'i' field of Table 1

• SDPKey that stores the key method and the key value itself as a string

• SDPMedia that stores the codec parameters, the media type, the number of ports the port itself and the transport protocol of the media

• SDPOrigin that stores the address type, the net type, the session ID, the session version the unicast address and the session name

• SDPPhoneNumber that contains the actual phone number and a description field

• SDPRepeated that stands for repetition settings. It stores the active duration, the offset and the repeated interval information

• SDPSessionName stands for the name of the session that is the 's' field in Table 1

• SDPTime stores the start and end time fields and the information about field repetition

• SDPUri stores the 'u' field of Table 1

Ozeki.VoIP.SDP.Message.SDPFields.SDPAttributes namespace for actual SDP attributes

This namespace contains three classes for concrete attribute values (ConcreteSDPAttributes), attribute format parameters (SDPAttrFmtp) that contains the format information and the format specific parameters and the RTP map information that is SDPAttrRtpmap class

Ozeki.VoIP.SDP.Message.SDPFields.SDPAttributes.ICE namespace for ICE NAT traversal policy

This namespace contains classes for handling the NAT traversal policy that is ICE in case of SDP in Ozeki VoIP SIP SDK. The classes in the Ozeki.VoIp.SDP.Message.SDPFields.SDPAttributes.ICE namespace are the following:

• SDPAttrCandidate that stores a candidate for an SDP attribute

• SDPAttrIceLite that is a session-level attribute only, and indicates that an agent is a lite implementation

• SDPAttrIceMismatch that is a media-level attribute only, and when present in an answer, indicates that the offer arrived with a default destination for a media component that didn't have a corresponding candidate attribute

• SDPAttrIcePwd that stands for storing the ICE password

• SDPAttrIceUfrag that stores the fragment information for the SDP

Ozeki.VoIP.SDP.MessageManipulator namespace for modifying SDP flows

This namespace contains an interface that is ISDPMessageManipulator and a class called IdSDPMessageManipulator that is an instance of the ISDPMessageManipulator interface.

This namespace class (IdSDPMessageManipulator) is the only tool you can reach and use for setting any of the SDP information if you really want to do it. However it is a possibility to modify SDP fields, Ozeki VoIP SIP SDK makes all the necessary settings for you about SDP so you will never feel urge to use this class at all.

IdSDPMessageManipulator class provides two methods, one for sending and one for receiving SDP messages. These methods can be called if you need to perform SDP message sending yourself.

Ozeki.VoIP.SDP.SDPProvider namespace for providing SDP flows

This namespace contains the basic classes and tools that are to provide the SDP support in Ozeki VoIP SIP SDK. It defines an interface (ISDPProvider), two classes (CommunicationModeHelper and SimpleSDPProvider) and an Enum type (CommunicationMode) that is for defining the mode of communication.

CommunicationMode can have the values of ReceiveOnly, SendOnly, SendReceive and Unknown. When Ozeki VoIP SDK produces a new SDP provider object it sets this mode to be able to identify the role of the SDP message.

SimpleSDPProvider class is a representation of a default SDP provider that is mostly used in Ozeki VoIP SIP SDK. The parameters of this provider can be modified if needed but it basically has the necessary settings for SDP messages.

By this point, you know all the tools and namespaces that provide the SDP support in Ozeki VoIP SIP SDK and you have surely realized that the SDK gives you all the background so SDP handling will not bother you at all while programming your Ozeki VoIP SIP SDK supported softphone solutions.

This example program covers much more than the SDP message manipulation, but in this article you will only learn the code that is related to the SDP message manipulation. If you want to know the further abilities, please check the following articles too:

• Operating with Incoming SIP Messages
• Inject SIP Messages
• Operating with Outgoing SIP Messages

The example program has a simple GUI with tabs that indicate the certain functionalities of the application. The SDP manipulation can be done on the second tab labeled with "Custom SDP Message" (Figure 4). You can manipulate both incoming and outgoing SDP messages.

Figure 4 - The graphical user interface of the message manipulator program

If you want to manipulate SDP or SIP messaged during the phone calls, you need to set message manipulators for the softphone like it is shown in Code 1.

private void SetCustomMessageManipulators()
{
    if (softPhone != null)
    {
        softPhone.SetSIPMessageManipulator(sipMessageManipulator);
        softPhone.SetSDPMessageManipulator(sdpMessageManipulator);
    }
}

Code 1 - Setting message manipulators for the softphone object

The SetCustomMessageManipulator method is called during the application initialization process. The SetSDPMessageManipulator method of the softphone needs an ISDPMessageManipulator parameter, therefore you need to implement that interface in a new class (Code 2).

class SDP_CustomMessageManipulator : ISDPMessageManipulator
{
        public string CustomIncomingMessage { get; set; }
        public string CustomOutgoingMessage { get; set; }

        public string PerformReceivedMessage(string incomingMessage)
        {
            if (string.IsNullOrEmpty(CustomIncomingMessage))
                return null;

            return CustomIncomingMessage;
        }

        public string PerformSendMessage(string outGoingMessage)
        {
            if (string.IsNullOrEmpty(CustomOutgoingMessage))
                return null;

            return CustomOutgoingMessage;
}

Code 2 - An ISDPMessageManipulator class

This class implements the two methods defined for sending and receiving SDP messages. The sdpMessageManipulator object that was used as a parameter for the softPhone.SetSDPMessageManipulator method call is an instance of this class.

In order to manipulate an outgoing SDP message, you need to set the outgoing message you want to send and press the Apply button below the textbox. The event handler for this button is shown in Code 3.

private void btnSDPApplyOutgoing_Click(object sender, EventArgs e)
{
    sdpMessageManipulator.CustomOutgoingMessage = tbOutgoingSDP.Text;
}

Code 3 - Applying a custom outgoing SDP message

Working with incoming SDP messages is just the same. You type in the modified message and press the apply button below the proper textbox. The event handler shown in Code 4 will do the rest for you. This method uses the same tools that were mentioned above.

private void btnSDPApplyIncoming_Click(object sender, EventArgs e)
{
    sdpMessageManipulator.CustomIncomingMessage = tbIncomingSDP.Text;
}

Code 4 - Manipulating incoming SDP messages

Now you are familiar with the basics about manipulating incoming and outgoing SDP messages using the Ozeki VoIP SDK provided tools. Now it is time to take a step further for creating your own softphone solution that performs all the features you need.

This article introduced the basic concepts about SDP and the usage of it in Ozeki VoIP SIP SDK. If you have read through this page carefully, now you are perfectly familiar with all the terms concerning SDP and you also know that Ozeki VoIP SIP SDK does everything that has to be done with them in the background, so you won't need to write a single code line in direct relation to the SDP tools.

By this time, you have surely realized that as necessary the SDP support is, as easily you can use it with Ozeki VoIP SIP SDK, so you can have no doubt that you need Ozeki VoIP SIP SDK for building your own softphone solution that is fully capable of working with SDP.

If you have any questions or need assistance, please contact us at info@voip-sip-sdk.com

You can select a suitable Ozeki VoIP SIP SDK license for your project on Pricing and licensing information page

Related Pages

• For the basic knowledge about softphones visit the How to build a softphone site
• For the basic knowledge about integrating Ozeki VoIP SIP SDK: Quick start guide
• Download Ozeki VoIP SIP SDK form the Ozeki VoIP SIP SDK download page
• For further examples using Ozeki VoIP SIP SDK, visit the SIP voice applications site