Click here to Skip to main content
Click here to Skip to main content

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

, 30 Jul 2010
Rate this:
Please Sign up or sign in to vote.
This article is a technical overview of the Session Description Protocol, and is designed for Java, C#, and VB programmers who want a quick low-level guide to the workings and details of the protocol.

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.

Table 1. Session Description
Field Type Opt/Mnd Description
Protocol Version v M The current protocol version. Always "0" using RFC4566.
Origin o M The session originator's name and session identifiers.
Session Name s M The textural session name.
Session Information i O Textural information about the session.
URI u O A pointer to supplemental session information.
Email Address e O Email contact information for the person responsible.
Phone Address p O Phone contact information for the person responsible.
Connection Data c C The connection type and address.
Bandwidth b C Proposed bandwidth limits.
Timing Descriptions Go Here
Time Zones z O Accounts for daylight saving information.
Encryption Keys K O A simple mechanism for exchanging keys. Rarely used.
Attributes A O One or more attributes that extend the protocol.
Media Descriptions Go Here

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

Timing Description

Table 2. Timing Description
Field Type Opt/Mnd Description
Timing t M Start and end times.
Repeat Times r O Specifies the duration and intervals for any session repeats.

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 1st 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

Table 3. Media Description
Field Type Opt/Mnd Description
Media Descriptions m M Media definitions including media type (e.g., 'audio'), transport details, and formats.
Session Information Same as above
Connection Data Same as above
Bandwidth Same as above
Encryption Keys Same as above
Attributes Same as above

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.

Table 4. Sample Attributes
Attribute Form Description
Category cat:<category> A dot-separated hierarchical category used for filtering sessions.
Keywords keywds:<keywords> Assists in the identification of sessions.
RTP Payload Type rtpmap:<payload type> <encoding name>/<clock rate> Maps an RTP payload to the encoding, format, and clock rate.
Receive Only recvonly Tools should start in receive-only mode.
Send/Receive sendrecv Tools can start in send and receive mode.
Type type:<conference type> Types include "broadcast", "meeting", and "moderated"
Charset charset:<character set> The character set used in the session name and information fields.
Language lang:<language tag> The default language for the session.

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 1st 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.
  2. SdpMessage sdp = new SdpMessage();
  3. 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.
  4. sdp.Origin.UserName = "jdoe";
    sdp.Origin.SessionId = 2890844526;
    sdp.Origin.SessionVersion = 89; 
    sdp.Origin.Address = new IPHost("214.191.7.5");
  5. Add the session name and information, including a pointer to a website with more info.
  6. sdp.SessionName = "SDP Implementation";
    sdp.SessionInformation = "A Seminar on the session description protocol";
    sdp.Uri = new Uri("http://www.arrhussdp.com/documents/sdpseminar.html");
  7. Add the contact information for the person responsible. The email for John Doe, which includes a full name.
  8. sdp.Emails.Add(new EmailHeaderField("jdoe@arrhus.com", "John Doe"));
  9. 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.
  10. sdp.Connection.Address = new IPHost("100.101.102.103");
  11. 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 1st of August 2010.
  12. 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);
  13. 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.
  14. sdp.Attributes.Add(new AttributeHeaderField("recvonly"));
  15. 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.
  16. MediaHeaderField mh = new MediaHeaderField(SdpMedia.Audio,49172,
                          SdpMediaProtocol.RtpAvp,"0"); 
    sdp.MediaDescriptions.Add(new MediaDescriptionHeaderField(mh));
  17. 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.
  18. 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.

Table 5. Recommended SIP Stacks
Lang Link Description
Java NIST's SIP library Reference API from the National Institute of Standards and Technology.
C#, VB etc. Konnetic's SIP .NET Library Well documented low-level SIP and SDP stack.
C#, VB etc. Microsoft's Unified Comms Server High-level SIP, SDP, and RTP stack.
C++ PJSIP SIP Stack Lightweight, but fully complete and highly portable SIP stack.

Test Tools

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

Table 6. Recommended SIP Testing Tools
Tool Description
SIPp A SIP traffic generator from HP.
PROTOS Testing app from the University of Oulu, Finland.
ETSI TS 102 027-2 List of SIP test call flows.

Further Reading

Related Articles

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

Jesper A Nielsen
Software Developer (Senior)
Finland Finland
I've been programming since the early-90s. Since then I’ve gained a Master in Computer Science and published fundamental research on 4G technologies.
For a living I tend to use Microsoft technologies and I currently work in the telecommunications industry in Finland.

Comments and Discussions

 
Generalvoip sip sdk Pinmemberdan rogy7-Oct-10 4:20 
GeneralRe: voip sip sdk PinmemberJesper A Nielsen7-Oct-10 15:41 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.140827.1 | Last Updated 30 Jul 2010
Article Copyright 2010 by Jesper A Nielsen
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid