Introduction to SIP for Java, C#, and VB Developers
2011-03-04 15:18
465 查看
This article is a technical overview of the Session Initiation 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.
See Also
More like this
More by this author
Print Article
Twitter
Digg
Facebook
Del.icio.us
Reddit
Stumbleupon
Newsvine
Technorati
Mr. Wong
Yahoo!
Google
Windows Live
Send as Email
Add to your CodeProject bookmarks
Discuss this article
16
Report this article as inappropriate
Sponsored Links
In 2002, a revised version of the SIP standard was formalised into the Internet Engineering Task Force's (IEFT) standardisation process as RFC3261. Because of the open nature of the IETF standards process, the fact that SIP is text based and shares many features with existing specifications, it has been readily understood, extended, and implemented.
Since its emergence, SIP has gained traction as a facilitator of instant messaging (e.g., Windows Messenger) and VoIP (e.g., most well-known platforms apart from Skype).
A User Agent (UA) is the entity which represents an end user in a client device. It usually operates in two modes: a User Agent Client (UAC) sends the initial request messages and processes responses; and a User Agent Server (UAS) accepts requests and sends responses.
Proxy Servers are involved in routing the SIP messages to the correct endpoint. Stateful proxies sometime make use of User Agents in a logical entity called a Back-To-Back-User-Agent.
Redirect Servers provide a new address or different route path to the recipient. The server may make use of a Location Server to persist location information.
A Registrar acts as current repository of a client's attachment to the network.
It is the User Agent that tends to reside on the end user's device. The other entities provide essential support services in many scenarios.
Request: sent from client to a server and defines the operation sought by the client.
Response: sent from server to a client, and provides the status of that request.
Table 1. SIP methods
Table 2. Response classes
Within each class, numerous response codes have been predetermined - some copied from HTTP.
Table 3. Sample response codes
Collapse | Copy Code
Start-Line: formatted as a Request-Line for Requests, or a Status-Line for Reponses.
Headers: Named attributes that provide additional information about the message.
Separator Line: Separator between header and body.
Body: binary or textural payload. Typically, Session Description Protocol (SDP) or a message text.
The Start Line, each header line, and the Separator Line is terminated by a [CRLF] sequence.
Request-Line: Contains a method, URI, and ends with the protocol version ("SIP/2.0").
Collapse | Copy Code
Status-Line: Starts with the protocol version, followed by a numeric status code, and is completed with a short textural reason.
Collapse | Copy Code
Collapse | Copy Code
Each header can be separated on to different lines using a [CRLF][TAB or SPACE] sequence (known as folding). What's more, multiple headers with the same name, e.g., Contact can appear on separate lines, or, can be placed on the same line separated by commas. For example:
Collapse | Copy Code
Can be represented as:
Collapse | Copy Code
Or using folding:
Collapse | Copy Code
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 SIP 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 SIP's equivalent of the archetypal Hello World applications.
Collapse | Copy Code
Create the Via header; the Via header indicates to the recipient the return path.
Collapse | Copy Code
Create the addresses of the sender and recipient. The
Collapse | Copy Code
Create the unique identifiers for the call and the conversation.
Collapse | Copy Code
Create the alternate contact information for the sender.
Collapse | Copy Code
Finally, add the content definitions. We will omit the content in this example.
Collapse | Copy Code
Collapse | Copy Code
Add the Status Line, which indicates the request was a success.
Collapse | Copy Code
Copy over the Via header from the Request message.
Collapse | Copy Code
Copy over the address information. The To and From fields stay the same as the original, except for a tag parameter on the To field. They do not swap for the Response. You should think of them as the original To and From fields.
Collapse | Copy Code
Copy over the identifier from the Request message.
Collapse | Copy Code
Add the alternate contact information. This time it is for Bob.
Collapse | Copy Code
Finally, add the content definitions.
Collapse | Copy Code
I should note that a good library will provide APIs that automate much of the boilerplate code shown above. For example, the copying of fields from the Request to the Response would take place in the library.
Collapse | Copy Code
Figure 1. Alice completes an SIP call with Bob, exchanges media packets, then Bob terminates the call.
Bob's UA receives the INVITE and responds with a 100 Trying message.
The UA then attempts to attract the attention of Bob, and simultaneously sends a 180 Ringing message to Alice.
Bob respond and his UA sends a 200 OK message. The 200 OK contains the SDP message Bob is agreeing to.
Finally, Alice's UA acknowledges receipt of the OK with an ACK request.
Media streams are established directly between Alice and Bob.
We have now paved the way for another protocol (such as RTP) to transport the media data directly between Alice and Bob without further intervention from SIP. This transfer takes place in what is known as the Bearer or Transport Plane, with SIP acting within the Control or Signaling Plane.
Bob hangs up and his UA initiates a session termination by sending a BYE request to Alice.
Alice's UA response with a 200 OK.
In the above example, Alice and Bob carry on a generic "media" exchange. However, this could easily represent a voice-call, video-conferencing, or instant messaging session; the procedure would look exactly the same.
Table 4. Recommended SIP stacks
Table 5. Recommended SIP testing tools
A. B. Johnston, SIP: Understanding the Session Initiation Protocol, 3rd ed. Boston, MA, USA: Artech House, 2007.
J. Rosenberg et al., "SIP: Session Initiation Protocol" RFC3261 2002
IETF. (2010) Multiparty Multimedia Session Control (mmusic). [Online]. http://datatracker.ietf.org/wg/mmusic/
IETF. (2010) Session Initiation Protocol (SIP). [Online]. http://datatracker.ietf.org/wg/sip/
H. Schulzrinne et al., "RTP: A Transport Protocol for Real-Time Applications" RFC3550 2003.
Some of the above are IETF "Request For Comment" submissions. Don't let that put you off. Most RFCs are very well written and approachable. You'll learn a lot just by reading the first 10 pages.
See Also
More like this
More by this author
Print Article
Digg
Del.icio.us
Stumbleupon
Newsvine
Technorati
Mr. Wong
Yahoo!
Windows Live
Send as Email
Add to your CodeProject bookmarks
Discuss this article
16
Report this article as inappropriate
Article | Browse Code | Stats | Revisions (18) |
4.82 (34 votes) |
1 | 2 | 3 | 4 | 5 |
Session Initiation Protocol (SIP)
Session Initiation Protocol (SIP) was designed from the bottom up to connect people and devices whenever and wherever they are in order to engage in a (possibly lengthy) exchange of information. Existing protocols, such as HTTP and SMTP, were not purpose-built for this essential human activity, and so SIP was born to fill the gap. However, SIP borrows from these two other protocols heavily: from using HTTP's message exchange pattern, message format, and encoding, to SMTP's URI scheme.In 2002, a revised version of the SIP standard was formalised into the Internet Engineering Task Force's (IEFT) standardisation process as RFC3261. Because of the open nature of the IETF standards process, the fact that SIP is text based and shares many features with existing specifications, it has been readily understood, extended, and implemented.
Since its emergence, SIP has gained traction as a facilitator of instant messaging (e.g., Windows Messenger) and VoIP (e.g., most well-known platforms apart from Skype).
Entities
An SIP environment consists of a number of connected entities:A User Agent (UA) is the entity which represents an end user in a client device. It usually operates in two modes: a User Agent Client (UAC) sends the initial request messages and processes responses; and a User Agent Server (UAS) accepts requests and sends responses.
Proxy Servers are involved in routing the SIP messages to the correct endpoint. Stateful proxies sometime make use of User Agents in a logical entity called a Back-To-Back-User-Agent.
Redirect Servers provide a new address or different route path to the recipient. The server may make use of a Location Server to persist location information.
A Registrar acts as current repository of a client's attachment to the network.
It is the User Agent that tends to reside on the end user's device. The other entities provide essential support services in many scenarios.
Messages
SIP messages come in two flavours:Request: sent from client to a server and defines the operation sought by the client.
Response: sent from server to a client, and provides the status of that request.
Request
A SIP request is characterised as a method much like HTTP, and is considered a 'verb', since it requests actions to be performed by other User Agents or servers. RFC3261 defines six methods (the first six in Table 1), with subsequent standards defining the remaining extension methods (from INFO onwards).Table 1. SIP methods
Method | Description |
---|---|
INVITE | Used to set up an SIP session. Session parameters are negotiated. |
REGISTER | Authenticates the User Agent and provides a current location to the network. |
BYE | Terminates an open session. |
ACK | Confirms a success response to an INVITE. The third part to a three-way-handshake. |
CANCEL | Cancels an open request. BYE should be used to cancel (tear down) an existing request. |
OPTIONS | Queries the capabilities of correspondents. |
Extension Methods | |
INFO | Provides mid-call session-related information. It is rarely used. |
MESSAGE | Used to transfer Instant Messages. |
NOTIFY | Publishes the outcome of events. Used in combination with SUBSCRIBE requests. |
PRACK | A Provisional Response ACKnowledgment. Confirms receipt of a provisional response. |
PUBLISH | Publishes status information. Used for Instant Messaging presence services. |
REFER | Mechanism to pass a request to someone more appropriate to deal with it. |
SUBSCRIBE | Used to request receipt of future NOTIFY or PUBLISH requests. |
UPDATE | Modifies session parameters in mid-call. |
Responses
SIP Response messages are always sent in reply to a request. They convey status updates, confirmations, directions, and error codes back to the UAC originating the request. Responses are characterised as either provisional or final, and every response must be identified by a 3-digit code.Response Types
Six classes of response have been defined, and are categorised using the 3-digit code. The first five are borrowed from HTTP; the sixth is new to SIP.Table 2. Response classes
Class | Description |
---|---|
1xx Provisional | Confirms receipt of request and processing is continuing. Provisional responses to INVITEs are never ACKed. |
2xx Success | The request was received, processed, and accepted. |
3xx Redirection | Provides location information or alternative services to try. |
4xx Request Failure | The request contained an error or cannot be processed by the server. |
5xx Server Failure | The server is unable to fulfill the request because of an internal error. |
6xx Global Failure | No service can be found to fulfill the request. |
Table 3. Sample response codes
# | Reason Phrase | Description |
---|---|---|
100 | Trying | The next hop received the request. |
180 | Ringing | Attempting to alert the user. |
182 | Queued | Temporarily unavailable and request is in a queue (not rejected). |
200 | OK | The request has succeeded. |
301 | Moved Permanently | User is no longer available at the address given in the Request URI. |
302 | Moved Temporarily | Retry the request at a new address given in the Contact header. |
400 | Bad Request | Could not understand or process correctly the request. |
401 | Unauthorised | The request either failed authentication or needs more information. |
403 | Forbidden | The server is refusing to process the request. Do not retry. |
404 | Not Found | The server cannot identify the user in its domain. |
408 | Request Timeout | The server could not process the request in a reasonable time. |
415 | Unsupported Media | The format is not supported by the server. |
480 | Temporarily Unavailable | The called party is currently unavailable. |
485 | Ambiguous | The Request URI is ambiguous. |
486 | Busy Here | The called party is currently not willing or able to take the call. |
500 | Server Internal Error | The server encountered an unexpected condition. |
513 | Message Too Large | The message length exceeded a determined limit. |
603 | Decline | The user explicitly refused to accept the request. |
Warning Header Field
The Warning header field is used to carry additional information about the status of the response. The header defines a 3-digit code between 300 and 399, the host name, and a warning text.Collapse | Copy Code
Warning: 307 isi.edu "Session parameter 'foo' not understood".
Anatomy of a Message
Each SIP message begins with a Start-Line, followed by a sequence of headers, and separated from the message body by a carriage-return line-feed sequence (CRLF).Start-Line: formatted as a Request-Line for Requests, or a Status-Line for Reponses.
Headers: Named attributes that provide additional information about the message.
Separator Line: Separator between header and body.
Body: binary or textural payload. Typically, Session Description Protocol (SDP) or a message text.
The Start Line, each header line, and the Separator Line is terminated by a [CRLF] sequence.
Start Line
The start-line conveys the type of message and protocol version. For both Requests (Request-Line) and Responses (Status-Line), the start-line has three elements separated by spaces.Request-Line: Contains a method, URI, and ends with the protocol version ("SIP/2.0").
Collapse | Copy Code
INVITE sip:bob@897s.aarhus.com SIP/2.0
Status-Line: Starts with the protocol version, followed by a numeric status code, and is completed with a short textural reason.
Collapse | Copy Code
SIP/2.0 200 OK
Headers
Headers follow the same generic header format as HTTP. Each consisting of a case-insensitive ASCII encoded name and colon, followed by a value which is sometimes UTF8 encoded and usually case-sensitive. Each header can have one or more semi-colon separated parameters appended to the value, providing additional tags and features.Collapse | Copy Code
header-name: header-value(;parameter-name=parameter-value)*[CRLF]
Each header can be separated on to different lines using a [CRLF][TAB or SPACE] sequence (known as folding). What's more, multiple headers with the same name, e.g., Contact can appear on separate lines, or, can be placed on the same line separated by commas. For example:
Collapse | Copy Code
Contact: <sip:alice@atlanta.com> Contact: <sip:alice1@chicago.com>
Can be represented as:
Collapse | Copy Code
Contact: <sip:alice@atlanta.com>, <sip:alice1@chicago.com>
Or using folding:
Collapse | Copy Code
Contact: <sip:alice@atlanta.com>, <sip:alice1@chicago.com>
Body
A message body describes the session (using SDP), or contains opaque text or binary body parts containing the payload related to the session (e.g., MIME or Message formats). Bodies can appear in request or response messages.Header Fields
In the following examples, Alice makes a call to Bob using his SIP URI, 'sip:bob@897s.aarhus.com'. Bob answers Alice with a success Response. The message is an example of an INVITE request containing an SDP message being responded to with a "200" OK response.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 SIP 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 SIP's equivalent of the archetypal Hello World applications.
Creating the Request Message
Add the Request Line, which indicates the message is an INVITE request to 'sip:bob@897s.aarhus.com'.Collapse | Copy Code
Invite invite = new Invite(new SipUri("sip:bob@897s.aarhus.com"));
Create the Via header; the Via header indicates to the recipient the return path.
Collapse | Copy Code
invite.ViaHeaders.Add(new ViaHeaderField("122.181.8.8:11506", SipTransportProtocol.Udp));
Create the addresses of the sender and recipient. The
SipUris can be an IP address, but fully qualified domain names are recommended. Display names are possible. For security reasons, the From header is allowed to be anonymous if desired.
Collapse | Copy Code
invite.From.Uri = new SipUri("sip:bob@897s.aarhus.com"); invite.From.DisplayName = "Bob"; invite.From.Tag = "769122"; invite.To.Uri = new SipUri("sip:alice@ml99.odense.com"); invite.To.DisplayName = "Alice";
Create the unique identifiers for the call and the conversation.
CallIdis a unique value for the session. The sequence is incremented in subsequent Requests. The To, From, and Call-ID tuple provides a unique key for a call.
Collapse | Copy Code
invite.CallId.CallId = "afh7989asdfhf@ml99.odense.com"; invite.CSeq.Sequence = 3434534; invite.CSeq.Method = SipMethod.Invite;
Create the alternate contact information for the sender.
Collapse | Copy Code
invite.ContactHeaders.Add(new ContactHeaderField( new SipUri("sip:alice2@vejle.com")));
Finally, add the content definitions. We will omit the content in this example.
Collapse | Copy Code
invite.ContentType.MediaType = "application"; invite.ContentType.MediaSubType = "sdp"; invite.ContentLength = 136;
SIP Request Message
The resulting SIP request message should look similar to the following:Collapse | Copy Code
INVITE sip:bob@897s.aarhus.com SIP/2.0 Via: SIP/2.0/UDP 124.191.8.8:11506 Max-Forwards: 70 To: Bob <sip:bob@897s.aarhus.com> From: Alice <sip:alice@odense.com>;tag=769122 Call-ID: afh7989asdfhf@ml99.odense.com CSeq: 3434534 INVITE Contact: <sip:alice2@vejle.com> Content-Type: application/sdp Content-Length: 136
Creating the Response Message
If you recall, in this example, Bob answers Alice with a success Response. The message is an example of a "200" OK response.Add the Status Line, which indicates the request was a success.
Collapse | Copy Code
Response okMessage = new Response(StandardResponseCode.Ok);
Copy over the Via header from the Request message.
Collapse | Copy Code
okMessage.ViaHeaders.Add(new ViaHeaderField("122.181.8.8:11506", SipTransportProtocol.Udp));
Copy over the address information. The To and From fields stay the same as the original, except for a tag parameter on the To field. They do not swap for the Response. You should think of them as the original To and From fields.
Collapse | Copy Code
okMessage.From.Uri = new SipUri("sip:bob@897s.aarhus.com"); okMessage.From.DisplayName = "Bob"; okMessage.From.Tag = "769122"; okMessage.To.Uri = new SipUri("sip:alice@ml99.odense.com"); okMessage.To.DisplayName = "Alice"; okMessage.To.Tag = "abgj67";
Copy over the identifier from the Request message.
Collapse | Copy Code
invite.CallId.CallId = "afh7989asdfhf@ml99.odense.com"; invite.CSeq.Sequence = 3434534; invite.CSeq.Method = SipMethod.Invite;
Add the alternate contact information. This time it is for Bob.
Collapse | Copy Code
okMessage.ContactHeaders.Add(new ContactHeaderField( new SipUri("sip:bob2@vejle.com")));
Finally, add the content definitions.
Collapse | Copy Code
okMessage.ContentType.MediaType = "application"; okMessage.ContentType.MediaSubType = "sdp"; okMessage.ContentLength = 132;
I should note that a good library will provide APIs that automate much of the boilerplate code shown above. For example, the copying of fields from the Request to the Response would take place in the library.
SIP Response Message
The resulting SIP response message should look similar to the following:Collapse | Copy Code
SIP/2.0 200 OK Via: SIP/2.0/UDP 124.191.8.8:11506 To: Bob <sip:bob@897s.aarhus.com>;tag=abgj67 From: Alice <sip:alice@odense.com>;tag=769122 Call-ID: afh7989asdfhf@mel99.odense.com CSeq: 3434534 INVITE Contact: <sip:bob2@vejle.com> Content-Type: application/sdp Content-Length: 132
Call Flow Example
This section details a call flow between that same two SIP User Agents as above, and could use the same message structures. The successful calls show the initial signaling, the establishment of the media session, then finally the termination of the call.Figure 1. Alice completes an SIP call with Bob, exchanges media packets, then Bob terminates the call.
Session Setup
Alice's UA sends an INVITE message to Bob's SIP address (i.e., 'sip:bob@897s.aarhus.com'). The message content is a Session Description Protocol message describing the expected media exchange.Bob's UA receives the INVITE and responds with a 100 Trying message.
The UA then attempts to attract the attention of Bob, and simultaneously sends a 180 Ringing message to Alice.
Bob respond and his UA sends a 200 OK message. The 200 OK contains the SDP message Bob is agreeing to.
Finally, Alice's UA acknowledges receipt of the OK with an ACK request.
Media streams are established directly between Alice and Bob.
We have now paved the way for another protocol (such as RTP) to transport the media data directly between Alice and Bob without further intervention from SIP. This transfer takes place in what is known as the Bearer or Transport Plane, with SIP acting within the Control or Signaling Plane.
Session Tear Down
At the end of the call, SIP is used to tear down the session. If, for example, it is Bob who ends the call, the exchange would be as follows:Bob hangs up and his UA initiates a session termination by sending a BYE request to Alice.
Alice's UA response with a 200 OK.
In the above example, Alice and Bob carry on a generic "media" exchange. However, this could easily represent a voice-call, video-conferencing, or instant messaging session; the procedure would look exactly the same.
SIP Libraries and APIs
The list is not exhaustive; they are simply the best ones I've come across. A sensible criterion to use for a good SIP API is whether it provides support for strongly typed header fields, implements SIP transactions, and encapsulates most of the SIP URI internals.Table 4. Recommended SIP stacks
Language | 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 5. Recommended SIP testing tools
Tool | Description |
---|---|
SIPp | An 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. |
Torture Tests | Torture tests. |
Wireshark | Arguably the best network analyser available. (Thanks to Ray Cassick for reminding me.) |
Further Reading
H. Schulzrinne. (2010) Henning Schulzrinne. [Online]. http://www.cs.columbia.edu/~hgs/A. B. Johnston, SIP: Understanding the Session Initiation Protocol, 3rd ed. Boston, MA, USA: Artech House, 2007.
J. Rosenberg et al., "SIP: Session Initiation Protocol" RFC3261 2002
IETF. (2010) Multiparty Multimedia Session Control (mmusic). [Online]. http://datatracker.ietf.org/wg/mmusic/
IETF. (2010) Session Initiation Protocol (SIP). [Online]. http://datatracker.ietf.org/wg/sip/
H. Schulzrinne et al., "RTP: A Transport Protocol for Real-Time Applications" RFC3550 2003.
Some of the above are IETF "Request For Comment" submissions. Don't let that put you off. Most RFCs are very well written and approachable. You'll learn a lot just by reading the first 10 pages.
Related Articles
An Introduction to SDPLicense
This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)About the Author
Jesper A Nielsen Software Developer (Senior) Finland Member | 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. |
相关文章推荐
- OSWorkflow: A guide for Java developers and architects to integrating open-source Business Process M
- OSWorkflow: A guide for Java developers and architects to integrating, open-source Business Process Management (Paperback)
- Website for the introduction to Matlab and Java
- Website for the introduction to Matlab and Java
- Website for the introduction to Matlab and Java
- Website for the introduction to Matlab and Java
- The Basics of the MMAPI for Java Developers -> Introduction to the MMAPI
- Website for the introduction to Matlab and Java
- Developer Introduction to Workflows for Windows SharePoint Services 3.0 and SharePoint Server 2007
- Brief introduction to Scala and Breeze for statistical computing
- Failed to connect to /XXXfor block, add to deadNodes and continue. java.net.NoRouteToHostException:
- 今天从http://eclipse.org/下载了一个Eclipse IDE For Java EE Developers,解压后启动,发现弹出提示框“ Failed to create the Java Virtual Machine”
- DEPLOYING NATIVE UWP (UNIVERSAL WINDOWS PLATFORM) APPS FOR JAVA DEVELOPERS & PUBLISHING THEM TO THE MICROSOFT STORE
- JavaTech, an Introduction to Scientific and Technical Computing with Java
- Java Cookbook, 3rd Edition Solutions and Examples for Java Developers
- An Introduction to WCF for Device Developers
- How to support both ipv4 and ipv6 address for JAVA code.
- Ruby on Rails for PHP and Java Developers
- 10 Best HTML5 Sliders For Designers and Developers to Beautify Their Websites
- Introduction to Java programming, Part 2: Constructs for real-world applications