Introduction to SDP for Java, C#, and VB Developers

Session Description protocol (SDP)

With the advent of protocols used to negotiate and define a communication session's parameters (e.g., Session Initiation Protocol), there was a need to explain the purpose and enrolment process. Session Description Protocol (SDP), defined in RFC4566, achieves that by providing a format for session characterisation and media definition. As part of a session negotiation, the parties are expected to agree on the descriptive values, timings, their respective capabilities, and desired media formats. This exchange is referred to as the Offer/Answer Model, and is formalised in RFC3264. SDP can be used with a number of transport protocols, such as Session Announcement Protocol (SAP), Session Initiation Protocol (SIP), Hypertext Transfer Protocol (HTTP), and others.

Contents

Several important pieces of information are mandatory within an SDP message:

• Session name.
• Time(s) the session is active.
• The media comprising the session.
• The owner/originator of the session.
• How to receive the media (addresses, ports, etc.).

Other optional information may also be provided:

• Bandwidth to be used by the conference.
• The purpose of the session.
• Contact information for the person responsible for the session.
• Time zone information.
• Session attributes extending SDP.

The encoding of the protocol is primarily UTF8 (descriptive fields can have other encoding as specified with a 'charset' attribute - defined later). Each piece of information is conveyed in a field. Each field is separated from the next by a carriage return/ line feed sequence [CRLF]. The form of each field is:

<type> = <value>

where <type> is a case-insensitive and unique single character field name, and <value> is structured text whose format depends upon <type>. They are separated by an unpadded '=' (equal) sign.

Message Structure

Within an SDP message, there are three main sections, detailing the Session, Timing, and Media descriptions. Each message may contain more than one Timing and Media description. Each field must appear in the order shown:

Session Description

Table 4 breaks down the message and describes each part in more detail.

Note: M - mandatory; O- optional; C- Conditional (Connection Data must appear in either the Session or Media descriptions).

Timing Description

Times are represented as Network Protocol Time (RFC1305): the number of seconds since 1900; intervals can be represented with NTP times or in typed time: a value and time units (days ('d'), hours ('h'), minutes ('m'), and seconds ('s')) sequence.

Thus, an hour meeting from 10am on 1^st August 2010, with a single repeat time a week later at the same time, can be represented as:

t=3487140000 3487143600
r=604800 3600 0

Or using typed time:

t=3487140000 3487143600
r=7d 3600 0

Media Description

Attributes

SDP uses attributes to extend the core protocol. Attributes can appear within the Session or Media sections, and are scoped accordingly as "session-level" or "media-level".

Attributes take two forms:

• A property form: "a=<flag>" conveys a property of the session.

• A value form: "a=<attribute>:<value>" provides a named parameter.

Example

Below is an example session description for a seminar presentation on "SDP Implementation" available in audio and video over RTP from address 100.101.102.103 using ports 49170 and 51372, respectively. It is an hour long seminar which starts at 10am on 1^st August 2010, and the contact is John Doe at jdoe@arrhus.com.

Note: All the code examples are fairly language agnostic. A list of recommended Java, .NET, and C++ APIs is given at the end for those interested in exploring SDP further. And all the code should work with any of them with little annotation (I've happened to have used Konnetic's SIP C# API in this case).

Note: Alice calling Bob is SDP's equivalent of the archetypal Hello World applications.

1. Create an SDP message or structure. The version of the protocol is "0" for RFC4566.
C#

SdpMessage sdp = new SdpMessage();

2. Add the Origin field with the unique session ID, version, and originator's name and address - the address can be either an IP address or a Fully Qualified Domain Name. In this example, jdoe is the originator. The session ID is 2890844526 and the version is 89. The session was created on machine 214.191.7.5.

sdp.Origin.UserName = "jdoe";
sdp.Origin.SessionId = 2890844526;
sdp.Origin.SessionVersion = 89; 
sdp.Origin.Address = new IPHost("214.191.7.5");

3. Add the session name and information, including a pointer to a website with more info.
C#

sdp.SessionName = "SDP Implementation";
sdp.SessionInformation = "A Seminar on the session description protocol";
sdp.Uri = new Uri("http://www.arrhussdp.com/documents/sdpseminar.html");

4. Add the contact information for the person responsible. The email for John Doe, which includes a full name.
C#

sdp.Emails.Add(new EmailHeaderField("jdoe@arrhus.com", "John Doe"));

5. Add the connection information about how to receive the session. The address can be either an IP address or a Fully Qualified Domain Name. In this example, an IP connection to the session host is used.
C#

sdp.Connection.Address = new IPHost("100.101.102.103");

6. Add the timings. There is at least one, and can be more than one time field. A good API will allow you to provide either NTP time or a DateTime. The output for times will always be the number of seconds since 1900 for the timings (3487140000 and 3487143600, respectively). These timings represent an hour meeting at 10am on the 1^st of August 2010.
C#

TimeDescriptionHeaderField td = new TimeDescriptionHeaderField();
td.Timings.Start = new SdpTime(new DateTime(2010, 7, 1, 10, 0, 0, 0));
td.Timings.Stop = new SdpTime(new DateTime(2010, 7, 1, 11, 0, 0, 0));
sdp.TimeDescriptions.Add(td);

7. Now, we can add the attributes for the session. This attribute is scoped to the session, and indicates that applications should begin the session in receive-only mode.
C#

sdp.Attributes.Add(new AttributeHeaderField("recvonly"));

8. In this example, we are adding two media description sections. The first is for audio on port 49170, using RTP Profile for Audio and Video Conferences with Minimal Control running over UDP. The final zero is an extra parameter information for RTP/AVP.
C#

MediaHeaderField mh = new MediaHeaderField(SdpMedia.Audio,49172,
                      SdpMediaProtocol.RtpAvp,"0"); 
sdp.MediaDescriptions.Add(new MediaDescriptionHeaderField(mh));

9. The second media description is for video on port 51372 using RTP Profile for Audio and Video Conferences with Minimal Control running over UDP. The final 31 is an extra parameter information for RTP/AVP. This attribute is scoped to the media description. Any presentations will be in portrait.
C#

MediaHeaderField mh1 = new MediaHeaderField(SdpMedia.Video, 51372, 
                       SdpMediaProtocol.RtpAvp, "31");
MediaDescriptionHeaderField md = new MediaDescriptionHeaderField(mh1);
md.Attributes.Add(new AttributeHeaderField("orient", "portrait"));
sdp.MediaDescriptions.Add(md);

Note: The two media descriptions (the lines beginning with m) define an audio and a video profile. These profiles are described in the Real Time Protocol (RTP) specification, RFC3550, and its travel companion RTP Profile for Audio and Video Conferences with Minimal Control, RFC3551.

SDP Message

The resulting SDP message should look exactly like the following:

v=0
o=jdoe 2890844526 89 IN IP4 214.191.7.5
s=SDP Implementation
i=A Seminar on the session description protocol
u=http://www.arrhussdp.com/documents/sdpseminar.html
e=jdoe@arrhus.com (John Doe)
c=IN IP4 100.101.102.103
t=3487140000 3487143600
a=recvonly
m=audio 49170 RTP/AVP 0
m=video 51372 RTP/AVP 31
a=orient:portrait

SDP Libraries and APIs

Typically, SDP APIs are implemented within SIP libraries - so the list coincides with the recommended SIP libraries. It is not exhaustive; they are simply the best ones I've come across. A sensible criterion to use for a good SDP API is whether it provides support for strongly typed fields, sensibly implements timings, and provides many helpful enumerations.

Test Tools

Testing tools are essential as sticking to the standard is demanded for any application interacting with other SIP applications and servers.

Further Reading

• M. Handley et al., "SDP: Session Description Protocol" RFC4566 2006.
• J. Rosenberg et al., "SIP: Session Initiation Protocol" RFC3261 2002.
• H. Schulzrinne. (2010) Henning Schulzrinne. [Online]. http://www.cs.columbia.edu/~hgs/
• A. B. Johnston, SIP: Understanding the Session Initiation Protocol, 3^rd ed. Boston, MA, USA: Artech House, 2007.
• H. Schulzrinne et al., "RTP: A Transport Protocol for Real-Time Applications" RFC3550 2003.

Related Articles

• An Introduction to SIP.