Konnetic
Unity SIP .NET SDK
Programmer's Guide
Version 4.0 February 2011
Table of Contents
1.
Programmer's Guide
1-2
2.
Unity SIP .NET SDK
4
2.1. Prerequisites for Unity SIP .NET SDK
4-5
2.2. Redistributable Components for Unity SIP .NET SDK
5
2.3. License Key Information
5-6
2.4. Ordering
6-7
2.5. Legal Information (Unity SIP .NET SDK)
7
2.5.1. License Agreement
7-10
3.
Session Initiation Protocol
11
3.1. SIP Entities
11-12
3.2. SIP Messages
12-15
3.3. Anatomy Of A Message
15-16
3.4. Header Fields
16-19
3.5. Call Flow Example
19-21
4.
Session Description Protocol
22
4.1. SDP Contents
22-23
4.2. Message Structure
23-25
4.3. SDP Attributes
25-26
5.
Introduction to the Library
30-31
5.1. Features
31-32
5.2. RFCs Implemented
32-34
5.3. Terminology
34-36
5.4. Permissions
36-37
5.5. Architecture
37-38
5.5.1. The Exception Model
38-41
5.5.2. Threading Model
41-42
5.5.3. Class Diagrams
42
5.5.3.1. Transaction Class Diagram
42-44
5.5.3.2. Transport Class Diagram
44-46
5.6. Application Programming Interface
46-48
5.7. SIP Transaction Objects
48
5.8. The SIP URI
48-51
5.9. Walkthrough: Initiate a Session
51-55
5.10. Walkthrough: Accept Or Decline A Session Invite
55-57
6.
Configuration
58
6.1. Common Client Settings
58-60
6.2. Low-Level Client Settings
60-64
7.
Working with the SipCore
67
7.1. Initialisation
67-69
7.2. Sip Core Behaviours
69-70
7.3. Event Processing
70-73
7.4. Listening For Incoming Messages
73-74
7.5. Sending Messages
74-76
8.
Working with Messages and Headers
77-78
8.1. SipMessage
78-79
8.2. Message Types
79-82
8.3. Adding Headers To Messages
82-83
8.4. Headers
83-85
8.5. Compact Form
85-87
9.
Working with Transactions
88
9.1. Transaction Entities
88-89
9.2. Transaction Types
89-90
9.3. Methods
90-91
9.4. State Machines
91-95
9.5. Timers
95-96
10.
Working with Authentication
97-98
10.2. The Authentication Exchange
99-101
11.
Working with the Transport Layer
102
11.1. Sip Connections
102-104
11.2. Connection Reuse
104-106
11.3. Introduction to TLS in SIP
106-107
11.4. Event Processing
108-109
11.5. IPv6
109-110
11.6. Transport Buffers
110-112
11.7. Example
112-113
12.
Working with SIP DNS
114
12.1. Implementation
114-117
12.2. Configuring DNS
117-118
This document is intended to give you an overview of the SIP and SDP protocols and describes how to use Konnetic's Unity SIP .NET library for developing SIP applications.
The current version is February 2011. New editions will have a new print date. Minor changes can occur without changing the print date.
The latest version of the document is always available at:
www.konnetic.com (http://www.konnetic.com/)
1.1 Intended Audience
This document is aimed at developers who wish to build SIP-based applications using the .NET platform. Readers are expected to be familiar with the following:
The C# .NET language. Basic Networking concepts.
Threading and exception handling concepts.
1.2 Getting Started
For a quick start to the library try the walkthroughs first. The Walkthrough: Initiate a Session
(Section 5.9) shows how an application developer can use the Unity SIP SDK to initiate a SIP
session by sending an INVITE request, listen for replies to that request, and finally respond with an ACK request to establish the session - sometimes called a Dialog in SIP. The Walkthrough:
Accept Or Decline A Session Invite (Section 5.10) takes the other side and listens for
requests and accepts or declines the request.
Read up about the License Key Information (Section 2.3) and how it is applied and works.
1.3 More Advanced
You can initiate sessions and receive incoming session requests using an intranet or local IP address - the samples make use of this technique (e.g. 'sip:[email protected]'). However, for more
advanced scenarios you will need a Fully Qualified Domain Name (FQDN) (e.g.
'sip:Name@Domain'). Ask your network administrator to provide you with a SIP URI or domain name, otherwise consider configuring a DNS server such as Windows Server 2008 or Bind. The SIP standard makes extensive use of DNS to resolve SIP URIs to IP Addresses, particularly in production
environments.
In order to get the most out of SIP you will need a SIP Registrar and/or SIP Proxy. You can obtain trial downloads of stable products from Brekeke (http://brekeke.com/) or Asterisk
(http://www.asterisk.org/).
1.4 Document Organisation
1.5 Konnetic Welcomes Your Comments
Konnetic welcomes your comments concerning this document. We are committed to providing documentation that meets your needs.
Send your comments or suggestions to: [email protected]
Include the document title, the print date and any comment on the document. Also, include what we did well, so we can incorporate that into other documentation.
Section 2 Provides legal and conceptual information about Unity SIP .NET SDK. Section 3 Provides a technical overview of Session Initiation Protocol.
Section 4 Provides a technical overview of Session Description Protocol. Section 5 Introduces the SIP library and its key components and architecture. Section 6 Details the configuration of the SIP library.
Section 7 Describes the basic code necessary to write an application using the SIP libraries and SipCore. Section 8 Describes the makeup of the SIP messages in the library and the header fields that make
up the message.
Section 9 Looks at the inner state machines in Transactions and describes how to use them to work with counterparties. Section
10 Introduces HTTP Digest and how it is handled in the SIP Library. Section
11
Describes the functioning of the TransportLayer and describes how to use it to listen for and sending messages.
Section
This document provides technical information about Konnetic's Unity SIP .NET SDK. It is intended to be read by application developers who are interested in creating and deploying SIP-based
applications. Typically for applications that require high functionality communication and
collaboration. This document consists of a general overview of the Unify SIP .NET API, guidance on some of the concepts involved with programming SIP applications using the Unify SIP .NET API.
2.1 Unity SIP .Net SDK
Use Konnetic's Unity SIP .NET SDK to create and deploy SIP-based applications and services. The applications can be client-based or server-based written in any .NET compliant language including C# and VB.NET. Target platforms include Mono and Microsoft's CLR.
The SDK provides the developer with a feature rich and fully standards compliant .NET library, supplementary documentation, and samples. The .NET library is especially useful for client applications, including those with low-power form factors.
2.1.1 Prerequisites
The following are the prerequisites for developing applications using Konnetic's Unity SIP .NET SDK.
Unity SIP .NET SDK installed on the development computer. A license for the product obtainable from Konnetic's website
(http://www.konnetic.com/).
A compatible .NET VSS (Virtual Execution System) and framework. Konnetic products support
Mono and the Microsoft CLR. We are committed to ensuring our products run on the platforms our customers demand.
For Windows Platforms
All our products are written against Microsoft's .NET 2.0 Framework and thus run against versions 2.0, 3.0, 3.5 and 4.0. We have found most of our customers support this version set. We are unable to provide binaries compiled against other, earlier, versions (i.e 1.0 and 1.1) of the Framework.
2
Unity SIP .NET SDK
For the time being min-CRL, the micro Framework and .NET CE are not supported.
For Other Platforms
Furthermore, our products are designed to run against Mono 2.6 and 2.7. Again earlier versions are not supported.
If you create an application that is built fromthe Unity SIP .NET SDK, the Redistributable Code is any software contained in the "bin" install directory. This will typically be .NET DLLs, supporting xml documents and possibly xsd scheme documents.
The software contains code that you are permitted to distribute in programs you develop as long as you fully comply with the terms of the License Agreement.
We need to charge for our software in order to pay our developers and to continue to supply you with quality products. Therefore Konnetic provides license management for our products.
We want you to use our product to create great applications and services your way. So once you have purchased a licensed copy you then have a royalty-free right to distribute the portions of the software designated as "Redistributable". Each license comes with a license key that you provide to unlock the software. The license key can be supplied at design time (license file or application configuration) or programatically at runtime.
2.3.1 Trial License
Konnetic provide a fully functional trial product using a license key that expires 30 after downloading the product. The licence key is found in the email sent at the same time as the download.
If your trial runs out you can contact [email protected]
(mailto:[email protected])and tell us what product you are evaluating. We'll arrange for
you to get a new 30 trial period license key.
2.2 Redistributable Components for Unity SIP .NET SDK
You have three options when using the license key: 1. Programatically
2. Configuration file (e.g. app.config) 3. License file ('lic' file)
The library will search each location in turn in the order specified above.
Programatically
Configuration File
Add the "license" element to the "<konneticSettings><sip>" configuration element.
License File
Find or create a konnetic.signalling.lic file and replace the whole contents of the file with the key. You may need to copy the konnetic.signalling.lic file into the application directory for each solution you use the evaluation in.
At Konnetic, we want to ensure you can get the most from our products. We offer freely
available fully functional evaluations of our software. You can deploy full purchased products royalty free. Each license grants one developer the ability to use and integrate the class libraries into the products they are developing.
We include license management software in all versions of the software, thus there is a license key to associate with the class library in order to use the product. You can achieve this though application configuration, programmatically at runtime or using a license file. We have worked hard to balance a solution that is not onerous to you, but at the same time deters piracy of our IP.
Konnetic.Signalling.Sip.LicenseContainer.Key = "PUT LICENSE KEY FROM EMAIL HERE";
<konneticSettings> <sip>
<!--The default SIP URI for the client-->
<license key="PUT LICENSE KEY FROM EMAIL HERE"/> </sip>
</konneticSettings>
We encourage you to evaluate our products extensively before making the decision to purchase. If you have any questions we will be happy to help during this period. Please note that we do not provide refunds.
Unity SIP .NET SDK can be purchased via the Konnetic website for immediate download from our partner site, Avangate.com. For further information, go to the purchase pages on the Konnetic web site:
Konnetic Website (http://www.konnetic.com/purchase/purchase.aspx)
The information contained in this document, including web site references, is subject to change without notice.
Complying with applicable copyright laws is the user's responsibility. No part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means, or for any purpose, without the express written permission of Konnetic Ltd.
Konnetic Ltd has copyright and other intellectual property rights covering subject matter in this document.
Sections of the documentation is the copyright of The Internet Society (2002). All other trademarks are the property of their respective owners.
KONNETIC LTD LICENSE AGREEMENT
READ CAREFULLY BEFORE INSTALLING THE SOFTWARE.
BY DOWNLOADING, INSTALLING AND/OR USING THE SOFTWARE OR CLICKING "I ACCEPT" WHEN PROMPTED IN CONJUNCTION THEREWITH, YOU ("LICENSEE") ACCEPT ALL OF THE TERMS AND CONDITIONS OF THIS LICENSE. IF YOU ARE ACCEPTING THESE TERMS ON BEHALF OF ANOTHER PERSON OR LEGAL ENTITY, YOU REPRESENT AND WARRANT THAT YOU HAVE FULL LEGAL AUTHORITY TO ACCEPT ON BEHALF OF AND BIND THAT PERSON
2.5 Legal Information (Unity SIP .NET SDK)
OR LEGAL ENTITY TO THESE TERMS. LICENSE AGREEMENT
This End User License Agreement ("EULA") is a legal agreement between you (either an individual or an entity) and Konnetic for the software product identified above, which may include user documentation provided in online or electronic form. By installing, copying, or otherwise using the SOFTWARE, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the SOFTWARE.
1. GRANT OF LICENSE
Konnetic grants to you as an individual or entity a non-exclusive License to make and use copies of the SOFTWARE in the manner provided below. The software is licensed, not sold.
(a) Evaluation License
Konnetic grants to you as an individual, a personal, nonexclusive License to install the SOFTWARE for the sole purposes of evaluating the SOFTWARE. You may evaluate the SOFTWARE for a period of thirty (30) days. After this period, you shall either (i) delete the SOFTWARE and all related documentation from all computers onto which it was installed or copied, or (ii) purchase a Single Developer License from Konnetic or one of its authorized suppliers to purchase the SOFTWARE. You may not under the terms of the evaluation License distribute any portion of the SOFTWARE or products generated using the SOFTWARE.
(b) Single Developer License
After you have purchased the License for the SOFTWARE, and have received a registration code enabling the registered copy, you are licensed to copy the SOFTWARE only into the memory of the number of computers corresponding to the number of Licenses purchased and activate the
SOFTWARE using the supplied registration code. The primary user of the computer on which each registered copy of the SOFTWARE is installed may make a second copy for his or her exclusive use on a second computer. Under no other circumstances may the SOFTWARE be operated at the same time on more than the number of computers for which you have paid a separate License fee. You may not duplicate the SOFTWARE in whole or in part, except that you may make copies of the SOFTWARE for backup or archival purposes. You have a royalty-free right to distribute the portions of the SOFTWARE designated as "Redistributable Code" under the terms below.
2. REDISTRIBUTABLE CODE
describes the files and Redistributable rights associated with each file of the Redistributable Code, subject to the requirements described below. You have a royalty-free right to distribute the portions of the SOFTWARE designated as "Redistributable Code" only if:
(a) You have purchased a License for the SOFTWARE.
(b) You distribute only the portions of the SOFTWARE designated as "Redistributable Code". (c) You use and distribute the "Redistributable Code" only in conjunction with the binary files that make use of them as a part of your software product.
(d) Your product(s) and application(s) must add significant and primary functionality to the SOFTWARE;
(e) You do not expose, document or make public the SOFTWARE API (Application Programming Interface);
(f) Your software product may not, in the reasonable opinion of Konnetic, compete with any Konnetic product.
(g) You agree to indemnify, hold harmless, and defend Konnetic and its suppliers from and against any and all claims or lawsuits including attorney's fees that arise or result from the use or
distribution of your software product. 3. RESTRICTIONS
You must not redistribute the registration codes provided, neither on paper nor electronically outside of that required to activate the SOFTWARE.
You must not redistribute any original or modified source code file or any portion of the source code contained within the files. You agree not to use the knowledge acquired from the source code in order to develop for yourself or any third party any program that is similar to or competitive with the Software. You are not allowed to port the source code to other programming languages.
You may not reverse engineer copy, duplicate or distribute the License schema that is needed to use the SOFTWARE in a design, development or runtime environment. You may not disassemble, decompile or reverse engineer the SOFTWARE or any portions of it.
You may not rent, lease, or lend the SOFTWARE. You may permanently transfer all of your rights under this EULA provided you transfer all copies of the SOFTWARE (including copies of all prior versions if the SOFTWARE is an upgrade) and registration codes and retain none, and the recipient agrees to the terms of this EULA.
4. TERMINATION
the terms and conditions of this EULA. In such event, you must destroy all copies of the
SOFTWARE. You may terminate this License at any time by destroying the original and all copies of the SOFTWARE in whatever form.
5. COPYRIGHT
The SOFTWARE is owned by Konnetic and is protected by Australian copyright laws and international treaty provisions. You may not copy the printed materials accompanying the
SOFTWARE (if any), nor print copies of any user documentation provided in on-line or electronic form.
6. LIMITED WARRANTY
THE PROGRAM IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL THE AUTHOR or AUTHORS BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING INCIDENTAL OR CONSEQUENTIAL DAMAGES, ARISING OUT OF THE USE OF THE PROGRAM, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. YOU ACKNOWLEDGE THAT YOU HAVE READ THIS LICENSE, UNDERSTAND IT AND AGREE TO BE BOUND BY ITS TERMS AS THE COMPLETE AND EXCLUSIVE STATEMENT OF THE AGREEMENT BETWEEN US,
SUPERSEDING ANY PROPOSAL OR PRIOR AGREEMENT, ORAL OR WRITTEN, AND ANY OTHER COMMUNICATIONS BETWEEN US RELATING TO THE SUBJECT MATTER OF THIS LICENSE.
7. LIMITATION OF LIABILITY
IN NO EVENT SHALL KONNETIC OR ITS SUPPLIERS BE LIABLE TO YOU FOR ANY
CONSEQUENTIAL, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OF ANY KIND ARISING OUT OF THE DELIVERY, PERFORMANCE, OR USE OF THE SOFTWARE, EVEN IF KONNETIC HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY EVENT, KONNETIC'S LIABILITY FOR ANY CLAIM, WHETHER IN CONTRACT, TORT, OR ANY OTHER THEORY OF LIABILITY, EXCEEDS THE LICENSE FEE PAID BY YOU.
Technical Overview
3.1 Introduction
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 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 SIP is text based and shares many features with existing
specifications, it has been readily understood, extended and implemented.
A SIP environment consists of a number of connected entities. These include, User Agents, Proxy servers, Redirect servers, Registrar servers and Back-to-Back User Agents (B2BUA). 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.
3.1.1 Clients
We naturally associate the concept of client software to the end users. This is even more applicable with SIP as it is indifferent to the device or application the person uses and attempts to abstract away the internet plumbing and make the person internet addressable. The User Agent (UA) is the entity typically hosted on client software and associated with end users. It has two modes of operation:
As a User Agent Client (UAC): Generates and sends requests those to servers (which may
include a UAS, see next), and receives responses in return.
As a User Agent Server (UAS): Receives and processes requests, and generates responses.
Typically a single UA acts in both capacities.
3
Session Initiation Protocol
3.1.2 Servers
SIP servers are instrumental in the location of clients and the efficient and correct routing of SIP messages.
Proxy Server: These elements are involved in routing the SIP Request to the correct UAS and
SIP Responses to the correct UAC. They are the most common type of server in a SIP
environment. If an exact address of the recipient is not know at elaboration the client sends the request to a proxy server which forwards it onto another proxy server closer to the end point or the ultimate recipient itself.
Redirect Server: A redirect server accepts requests from a client and responds to the client with
a new address or different route path to the recipient. They are important in supporting mobility – when a recipient has moved location.
Registrar: These servers act as current repository of a client’s location often utilising a separate
Location Server. User Agents register with a Registrar on start up or when the client changes the point of attachment to the network.
B2BUA: These logical entities act in a dual capacity in that they receive requests like a UAS,
process the request further in some manner, then behave as a UAC and forward the processed request on. B2BUA’s maintain state between calls and participate in SIP transactions providing tight control over the exchange. A stateful Proxy Server may contain a B2BUA.
SIP messages come in two flavours.
Request: sent from client to a server and define the operation sought by the client. Response: sent from server to a client and provide the status of that request
3.2.1 Requests
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 with subsequent standards defining the remaining extension methods (from INFO onwards).
3.2 SIP Messages
3.2.2 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.
INVITE Used to set up a SIP session. Session parameters are negotiated.
REGISTER Authenticates the User Agent and provides a current location to the network. BYE Terminates a 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.
Within each class, numerous response codes have been predetermined - some copied from HTTP.
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, processes 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 fulfil the request because of an internal error. 6xx Global
Failure No service can be found to fulfil the request.
# 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.
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.
Warning: 307 isi.edu "Session parameter ‘foo’ not understood"
Each SIP message begins with a Start-Line, is 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.
3.3.1 Start Line
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 Declined The user explicitly refused to accept the request.
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"). Status-Line: Starts with the protocol version, followed by a numeric status code and is
completed with a short textural reason.
3.3.2 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.
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 name same e.g. Contact can appear on separate lines, or, can be placed on the same line separated by commas. For example:
Contact: <sip:[email protected]> Contact: <sip:[email protected]> Can be represented as:
Contact: <sip:[email protected]>, <sip:[email protected]> Or using folding:
Contact: <sip:[email protected]>, <sip:[email protected]>
3.3.3 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.
3.4.1 Creating the Request Message
1. Add the Request Line, which indicates the message is an INVITE request to 'sip:[email protected]'.
InviteRequest invite = new InviteRequest(new SipUri("sip:[email protected]"));
2. Create the Via header, the Via header indicates to the recipient the return path.
invite.ViaHeaders.Add(new ViaHeaderField(new IPDomainPort("122.181.8.8:11506"), TransportProtocol.Udp));
3. 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 by anonymous if desired.
invite.From.Uri = new SipUri("sip:[email protected]"); invite.From.DisplayName = "Bob";
invite.From.Tag = "769122";
invite.To.Uri = new SipUri("sip:[email protected]"); invite.To.DisplayName = "Alice";
4. Create the unique identifiers for the call and the conversation. The CallId is 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.
invite.CallId.CallId = "[email protected]"; invite.CSeq.SequenceNumber = 3434534;
invite.CSeq.Method = SipMethod.Invite;
5. Create the alternate contact information for the sender. invite.ContactHeaders.Add(new ContactHeaderField(
6. Finally add the content definitions. We will omit the content in this example. invite.ContentType.MediaType = "application";
invite.ContentType.MediaSubType = "sdp"; invite.ContentLength = 136;
3.4.2 SIP request message.
The resulting SIP request message should look similar to the following: INVITE sip:[email protected] SIP/2.0
Via: SIP/2.0/UDP 124.191.8.8:11506 Max-Forwards: 70
To: Bob <sip:[email protected]>
From: Alice <sip:[email protected]>;tag=769122 Call-ID: [email protected]
CSeq: 3434534 INVITE
Contact: <sip:[email protected]> 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.
1. Add the Status Line, which indicates the request was a Success. Pass in the Request this is a response to
SipResponse okMessage = new SipResponse(invite, SipStatusCode.Ok);
2. Add the alternate contact information. This time it is for Bob. okMessage.ContactHeaders.Add(new ContactHeaderField(
new SipUri("sip:[email protected]")));
3. Finally add the content definitions.
okMessage.ContentType.MediaType = "application"; okMessage.ContentType.MediaSubType = "sdp"; okMessage.ContentLength = 132;
3.4.3 SIP response message.
The resulting SIP response message will look similar to the following: SIP/2.0 200 OK
Via: SIP/2.0/UDP 124.191.8.8:11506
To: Bob <sip:[email protected]>;tag=abgj67 From: Alice <sip:[email protected]>;tag=769122 Call-ID: [email protected]
CSeq: 3434534 INVITE
Contact: <sip:[email protected]> Content-Type: application/sdp Content-Length: 132
3.5.1 Successful Simple SIP to SIP
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 signalling, the establishment of the media session, then finally the termination of the call.
Figure 1. Alice completes a 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:[email protected]>).
The message contents are 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 is 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.
Session Tear Down
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.
Technical Overview
4.1 Introduction
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.
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
4
Session Description Protocol
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 the <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:
4.2.1 Session description
Table 4 breaks down the message and describes each part in more detail.
Table 1. Session Description.
4.2 Message Structure
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.
Note: M - mandatory; O- optional; C- Conditional (Connection Data must appear in either the Session or Media descriptions).
4.2.2 Timings description
Table 2. 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 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
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
Field Type Opt/
Mnd Description
Timing t M Start and end times.
r=7d 3600 0
4.2.3 Media description
Table 3. 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.
Table 4. Sample Attributes.
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
4.3 SDP Attributes
Example
Below is an example session description for a seminar presentation on "SDP Implementation" available in audio and video over RTP from address 124.198.100.6 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 [email protected].
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 then with little annotation.
Note: Alice calling Bob is SDP's equivalent of the archetypal Hello World applications. 1. Create and SDP message or structure. The version of the protocol is "0" for RFC4566. SdpMessage sdp = new SdpMessage();
2. Add the Origin field with the unique session Id, version and originators name and address - the address can be either an IP address or a Fully Qualified Domain Name. In this example jdoe is
Category cat:<category> 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.
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 IPDomain("214.191.7.5");
3. Add the session name and information including a pointer to a website with more info. sdp.SessionName = "SDP Implementation";
sdp.SessionInformation = "A Seminar on the session description protocol";
sdp.Uri = new Uri("http://www.mel99.melbournesdp.com/documents/sdpseminar.html"); 4. Add the contact information for the person responsible. The email for John Doe, which includes
a full name.
sdp.Emails.Add(new EmailHeaderField("[email protected]", "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.
sdp.Connection.Address = new IPHost("124.198.100.6");
6. Add the timings. There are 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 August 2010.
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.
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 extra parameter information for RTP/AVP.
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 extra parameter
information for RTP/AVP. This attribute is scoped to the media description. Any presentations will be in portrait.
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.
4.4.1 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.melbournesdp.com/documents/sdpseminar.html [email protected] (John Doe)
c=IN IP4 124.198.100.6 t=3487140000 3487143600
a=recvonly
m=audio 49170 RTP/AVP 0 m=video 51372 RTP/AVP 31 a=orient:portrait
Konnetic's Unity SIP .NET SDK is a class library written in C# that runs on Microsoft's CLR or Mono. The libraries provide an object model for developing SIP (IETF RFC 3261) based applications and services written against the .NET Framework 2.0 and later. Many of SIP's requirements and demands have been abstracted away leaving the developer to concentrate on high-level high-value application implementation. But at the same time the library still allows low-level configuration and control over SIP message flows using an event-based model.
The library provides advanced multi-threaded connection management designed to efficiently take advantage of multi-processor or multi-core hardware environments achieving high-performance in modern processors. It also enables a reliable communication model by supporting TCP
(Transmission Control Protocol); or provides for authentication and encryption through the use of TLS (Transport Layer Security); or allows higher throughput by using UDP (User Datagram Protocol).
SIP methods currently supported include REGISTER, INVITE, OPTIONS, ACK, BYE, CANCEL, INFO, UPDATE and MESSAGE.
SIP URIs are an important and complex part of the SIP standard. The Unity SIP .NET SDK provides a type safe SIP URI mechanism derived from the .NET Framework's System.Uri, System.UriParser and System.UriBuilder classes.
Other important features include full support for HTTP Digest Authentication, SIP DNS and an SDP library.
5.1 Overview
This section describes the SIP library architecture, the relationship between the objects, API, standards and different kinds of features.
Konnetic's implementation of SIP is designed primarily for clients, but can be used in server applications also. It allows you to build the following types of applications and services:
Media over IP. Collaboration tools.
A building block to develop a wide range of applications from mobile apps to desktop clients
applications and services.
Develop complete solutions for .NET managed platforms that implement call-level,
transaction-level and message-transaction-level functionality.
The SIP Stack component of the SIP Stack was developed in conformity with the specifications of RFC 3261 and various SIP extensions (see RFCs Implemented (Section 5.2)).
5.1.1 Methods
The SIP Stack supports baseline SIP methods, such as INVITE (Re-INVITE), ACK, BYE, CANCEL, OPTIONS and REGISTER. In addition extension methods supported are INFO, UPDATE and MESSAGE
5.1.2 Responses
The SIP Stack supports all response code classes (1xx to 6xx) specified in RFC 3261.
5.1.3 New Message Parameters
The SIP library can accept and encode new non-standard message parameters which do not appear in the baseline specification, such as methods, response codes, headers (extension header fields) and header parameters.
5.1.4 SIP DNS
The Unity SIP Library supports RFC3263: Session Initiation Protocol (SIP): Locating SIP Servers. NAPTR, SRV, A, AAAA DNS queries are all supported.
5.1.5 Interoperability
The Unity SIP Library passes RFC and European Telecommunications Standards Institute testing suites.
5.1.6 Parsing
Parsing of incoming messages is a fundamental feature of any SIP Library. Unity SIP Library uses a unique and powerful directed Deterministic Finite Automa engine to manage all header parsing.
5.1.7 Transports
UDP, TCP and TLS transport mechanisms are available. In addition client-only and mutual authentication is supported during the TLS exchange.
5.1.8 Security
The SIP Stack can authenticate any SIP request using the Digest authentication scheme in
conformity with the SIP specification. Both Client authentication and Server authentication (mutual) are supported. In addition Message Integrity (Auth-Int) is supported.
5.1.9 Multithreading
The SIP library runs in an internally multithreaded mode. Your application may either be single-threaded or multisingle-threaded. The SIP library uses synchronization mechanisms to ensure
multithreading safety at the level of individual objects, such as dialogs and transactions, as well as groups of object as in the transport layer.
The SIP library makes use of new threads to listen for incoming messages, and spawns new threads to handle each new message received.
The main implication for developer's is exceptions occuring within the multithreaded
environment are marshalled to either an event (e.g. OnListenerAborted event on the SipCore) or assigned to an exception property to be thrown on subsequent access to the object (e.g. Parsing exceptions on a SipMessage).
5.1.10 Low-Level Configuration
The SIP Stack configuration enables you to configure the following groups of parameters:
Default Message Properties Message Limits Network parameters Timer values Proxy Servers Miscellaneous
5.2 RFCs Implemented
5.2.1 RFCs Implemented
The following RFC have been directly implemented in the Unity SIP Library. Other RFC (e.g. covering TLS) are part of the underlying .NET framework and not included.
RFC Title Missing Functionality
RFC4566 Session Description Protocol None RFC4320 Actions Addressing Identified Issues with SIP's Non-INVITE Transaction. None RFC3596 DNS Extension to Support IP Version 6 None RFC3428 SIP Extension for Instant Messaging None RFC3581 An Extension to SIP for Symmetric
Response Routing None
RFC3311 SIP UPDATE Method None RFC3264 An Offer/Answer Model with the Session Description Protocol None
RFC3263 Locating SIP Servers
Section 4.1: NAPTR/SRV records being verified against TLS certificates.
Section 4.4: Consideration for stateless proxies.
RFC3261 Session Initiation Protocol
Section 8.2.7: Stateless UAS Behaviour Section 8.3: Redirect Server
Section 10.3: Processing REGISTER requests in a registrar
Section 13.2.2: Dialog creation from multiple 2xx responses
Section 16: Proxy Behaviour Section 23: S/MIME
RFC2976 SIP INFO Method None
RFC2782 A DNS RR for Specifying the Location of Services (DNS SRV) None RFC2617 HTTP Authentication: Basic and Digest
Access Authentication None RFC2119 The Naming Authority Pointer (NAPTR) DNS Resource Record None
5.2.2 Verification Standards
Testing of the library against industry standards in important to Konnetic. The following test suites have been used to verify that Unity SIP Library is fully compatible with the standard.
Connection
An association between two endpoints which carries packets across networks. Each endpoint is represented by a network address and port. In SIP, this concept is sometime referred to as a Flow. In the Unity SIP .NET API, a connection can use either TLS, TCP or UDP transport.
Konnetic's Unity SIP .NET API supports two types of connections: inbound and outbound. An inbound connection listens for incoming packets on an assigned local endpoint. Outbound connections initiate transmissions from the local endpoint to the correspondent. Outbound connections will typically use an ephemeral port number and subsequently listen on that port for responses.
Destination Tuple
A destination tuple contains the information needed to connect to a remote network device. It is formed of the IP Adddress of the remote device, the remote listening port and the transport protocol. Clients can either use the libraries DNS facility to resolve addresses, ports and transports, or can send messages directly using a destination tuple contained in the DestinationTuple object.
Dialog
A dialog represents a peer-to-peer SIP relationship between two or more user clients that persists for some time. It is analogous to a conversation or call, and is sometimes refer to as such. A session is typically associated with a dialog.
Header Field
Title Missing Functionality
RFC4475: SIP Torture Test Messages None ETSI: Conformance Test Specification for
SIP Proxy, Registrar, Redirect functionality was not tested
A header field is a component of the SIP message header. A header field can appear as one or more header field rows. Header field rows consist of a header field name and zero or more header field values. Multiple header field values on a given header field row are seperated by commas. Some header fields can only hvae a sinlge field value, and as a result, always appear as a single header field row.
Outbound Proxy
A proxy that receives requests from a client, even though it may not be the server IP
Address resolved by the Request-URI. Typically, a User Agent is manually configured with an outbound proxy, or can learn about one through auto-configuration protocols.
The ProxyServers config section allows the client application to configure the default outbound proxy servers for request messages. Alternative mechanisms are available to provide the proxy services, including on the SipCore.
The proxy servers are used by the outgoing message processsors to create a route-set on the message (unless a route header field is already present). The processor calculates the remote address of the message according to RFC3261 and RFC3263 and takes into account the existance of outbound proxy servers, Route header fields and loose routing rules.
There is a separate configuration for secure proxy servers to be configured as an outbound route-set for all secure transmissions. Only proxy servers with secure SIP URIs are allowed (e.g.
sips:proxy3.com) for secure transmissions.
Route Set
A route set is a collection of ordered SIP or SIP URI which represent a list of network nodes (typically proxies) that must be traversed when sending a particular request. A route set can be learned, through headers like Record-Route, or it can be configured.
SDP
Session Description Protocol, an IETF Internet standard (RFC 4566). It defines a format for
representing multimedia sessions. SDP objects are carried in the body of SIP messages and, based on the offer/answer model, are used to negotiate the media characteristics of a session between users.
Session
participate in some activity or exchange media descriptions required to establish media communication.
SIP
Session Initiation Protocol, an IETF Internet standard (RFC 3261).
SIP Transaction
SIP is a transactional protocol. Interactions between network elements take place in a series of independent message exchanges (Message Exchange Patterns). A SIP transaction consists of a single request and all following responses to that request. Two categories of transaction exist: those that are initated with an INVITE request (Invite Transactions), and those that are not (Generic
Transactions).
User Client
The device that hosts the SIP-based application.
The Unity SIP Library relies upon certain external resources to operate. Those resources must be available at runtime and access-control permissions must be set so as to allow the executing thread to access them. Additionally the library issues Code Access Security (CAS) demands upon the call stack at certain points in the operation.
The resources include:
Sockets - the SIP Library is a networked library and requires unrestricted access to network
sockets. A CAS demand is placed on the call stack whenever the library access the network.
DNS - Domain Name Service querys are a fundamental part of using SIP. The library requires
access to the DNS servers specified in the Konnetic.Net.NetworkInformation object. A CAS demand is placed on the call stack whenever the library issues a (non-cached) DNS query.
File IO - The library must have permission to read the configuration file, and any files it
dynamically links to.
Reflection - Internally the Unity SIP Library uses information about certain types when
executing. Furthermore, permission to invoke methods on types may be required in future
version.
The following diagram illustrates the overall architecture of the Unity SIP .NET API and important dependencies.
5.5.1 SIP Core
The SIP Core is the library facade (sometimes called an Aggregated class). It exposes important events, can control the most significate behaviours and methods of the library, sets the system configuration and other resources. The Core is also responsible for the initialization and termination of other layers. The Core provides an extensive event model to manage the processing of incoming and outgoing messages, subsequent processing or transport failures, and authentication and state data.
5.5.2 (Transactional) State
The transaction layer creates and manages transaction. Dialogs are usually associated with transactions. Each transaction is responsible for maintaining states, and sending and receiving
messages, acknowledgements and retransmissions using the transactional Timer. The transaction layer maps incoming messages to existing transactions and dialogs.
5.5.3 Transport
The transport layer handles SIP networking I/O. This layer manages UDP sockets and TCP connections, as specified in RFC3261, and sends and receives messages. Secure transmission is provided via TLS certificate exchange on a client-only or mutual basis.
5.5.4 Messages
Messages handle parsing and encoding of SIP messages. The message objects allow the strongly typed browsing and editing of the contents of SIP messages and also comparison of message parts, such as the SIP address. Validation of updates is provided as specified in RFC3261.
5.5.5 Parsing Engine
SIP is a text-encoded protocol, which means that messages are sent down the wire as a UTF8
encoded byte steam. Although encoding text messages is relatively simple, parsing them can be more complex because of the large degree of freedom provided by text grammar. SIP grammar is specified in RFC 3261 and uses an Augmented Bakus-Naur Form to represent the message syntax and
structure.
The SIP library uses a dedicated rule based DFA (Deterministic Finite Automaton) tokeniser/parser implemented according to the syntax and grammar of the protocol. This parser is optomised for performance and is thread-safe so that multiple messages can be parsed simultaneously in different thread contexts.
5.5.6 Authentication
SIP employs HTTP Digest authentication when establishing identiyy between elements. The Unity SIP Library uses a sophisticated authentication managment routine to control the lifetime of HTTP Digest exchanges.
5.5.7 DNS
RFC3263 governs how SIP resolves SIP URIs to IP Addresses. The Unity SIP Library provides a Linq friendly interface to the DNS querys and cache.
Konnetic follow the standard CLS model for reporting exceptions. User defined exceptions are thrown when a method cannot complete its task as indicated by its name. All user defined exceptions derive from SipException, which in turn derives from System.Exception.
The following exceptions are explicitly thrown within the Unity SIP .NET API, but other exceptions may originate from the Framework Class Library and are propagated up through the Unity SIP .NET API stack. For example, a System.Net.Sockets.SocketException may be thrown by the underlying network subsystem, or a resource constraint may cause a System.OutOfMemoryException to be thrown. Application designers need to consider subsystem exceptions when designing a robust exception policy.
5.5.1.1 Framework Class Library Defined Exception Classes
The following is a list of some of the standard .NET Framework exceptions that may be returned from the Unity SIP .NET API.
5.5.1.2 Unity SIP .NET API Specific Exception Classes
5.5.1 The Exception Model
ArgumentException The exception that is thrown when one of the arguments provided to a method is not valid.
ArgumentNullException The exception that is thrown when a null reference (Nothing in Visual Basic) is passed to a method that does not accept it as a valid argument.
ArgumentOutOfRangeException The exception that is thrown when the value of an argument is outside the allowable range of values as defined by the invoked method.
FormatException The exception that is thrown when the format of an argument does not meet the parameter specifications of the invoked method.
InvalidOperationException The exception that is thrown when a method call is invalid for the object's current state.
ObjectDisposedException The exception can be returned from the Transport Layer when sending messages.
TimeoutException The exception that is thrown when the time allotted for a process or operation has expired.
5.5.1.3 Exception Object Model
SipAggregateException
The aggregate exception wraps one-or-more inner exceptions. The exception is used to marshal a number of exceptions beyond the thread boundary. For example, the parsing of incoming message occurs on a thread spawned within the Transport Layer. Any parsing exceptions are wrapped in a SipAggreagateException and assigned to the SipMessage. The exception may be thrown on subsequent access to the SipMessage.
SipException The exception that is thrown when a generic SIP error occur. All SIP exceptions ultimately derive from this exception.
SipFormatException The exception that is thrown when a SIP formatting error occurs.
SipMessageSizeLimitException The exception that is thrown when parameters of a SIP message exceed the limit set.
SipOutOfRangeException The exception that is thrown when a value is semantically out of allowable range or a numeric overflow occurs.
SipParseException
The exception that is thrown when the parse method is invoked and it is detected that the passed arguments would result in illegal SIP syntax or semantics. It does not signify an invalid object.
SipSecurityException The exception that is thrown when an exception occurs in the authorization of sip messages.
SipTransactionException The exception that is thrown concerning an error in the transactional state machine for the message.
SipTransportException The exception that is thrown when an error occurs in the transport layer.
SipUriException
The exception that is thrown when a method is invoked and it is detected that the passed arguments would result in illegal SIP URI syntax or semantics.
SipUriFormatException The exception that is thrown when a SIP formatting error occurs when dealing with the SipUri class.
The Unity SIP Library makes extensive use of threads. The library uses asynchronous calls whenever possible. Thread pool worker threads are used to invoke application callbacks and some events are raised on seperate threads where responsivness is demanded.
Applications using the Unity SIP Library should not throw exceptions in these worker threads
because they will not be caught and handled appropriately within the Library and failure will result in the termination of the application.
The library does not raise events or invoke application-supplied callbacks inside syncronisation primatives.
5.5.3.1 Class Diagrams
The following diagrams illustrate some of the more important relationships within the class hierarchy of Unity SIP .NET API.
5.5.3 Class Diagrams
The SIP library provides an intuitive and object-orientated API for the development of SIP-enabled applications. The API includes a set of events that allow your application to intervene in different phases of message and transaction establishment and termination. The SIP library can be made fully functional and operational with the use of minimal configuration and initialisation.
The SIP Library API is divided into three layers, giving the user increasingly lower-level control of the functionality of messages and SIP library state machines. The highest level layer APIs abstracts away protocol complexity and provides for a simple interface to build SIP applications with minimal coding effort. Mid-level APIs enable sending and receiving messages from the primitive
(transaction) level interface, managing routing, authorization and configuration. Low-level APIs provide access to SIP messages and enable the application to modify the SIP Libraries core
functionality and behaviour. These APIs give the user tight control over the core SIP functionality, enabling you to rapidly deploy innovative functionality and to interwork with standard and even non-standard SIP applications. These different levels of APIs may be used in parallel, as described in more detail throughout this guide. This following sections describe the main API modules.
5.6.1 SIP Core API
The SIP Core API enables your applications to perform the following:
Initialisation and termination. Configuration
Event management
Start Listening for incoming messages Send outgoing messages
Authorization
5.6.2 Transaction State API
The Transaction API is centralised around the SipTransactionStateManager object, Transaction derived types and Dialog derived types. They manage the application's state.
Dialogs
The SipTransactionStateManager object enables you to terminate dialogs, modify exiting dialogs (re-INVITE) and more. The Dialog objects provide a set of events that provide you with the ability to add your own call processing logic to the application. Dialogs are created automatically by Invite Transactions.
Transactions
The SipTransaction derived types (GenericClientTransaction, InviteClientTransaction,
GenericServerTransaction, InviteServerTransaction) enable you to manage transactional state. The transaction may be related to a dialog (e.g. for a trasnaction begun with an INVITE) or not (e.g. OPTIONS related transactions). Using the API you can create new transactions, send outgoing requests, and respond to incoming requests. However, SipTransactions are typically automatically created when sending a request. Transactions provide a set of events that enable you to control some of the behaviour. In addition to their usage in clients you can use the transactions to implement SIP servers such as Registrars and Proxies.
5.6.3 Message API
The SipMessage object provides access to the SIP message content, enabling the application to browse and edit any part of the message. Messages parts are represented a First-Line, Headers and Body triumverate.
The SipMessage object also interfaces with the parsers and encoding formatters provided in the library.
Each message can be associated with a set of Authentication exchanges, a transaction and a recipient.
5.6.4 Transport API
The TransportLayer enables you to send a messages directly bypassing the authorization, routing and transactional processing. Furthoremore it provides control over connection reuse and listening on local ports.
SIP utilises DNS extensivly in order to resolve SIP URIs to IP addresses. The Unity SIP Library contains DNS querying functionality complicit with RFC3263. The SipDnsCache object contains the Naming Authority, Service Location and A/AAAA (IPv4/IPv6) caches.
The SipConfiguration object enables low-level configuration of the client parameters, transaction timers, message limits and behaviour.
5.6.6 Authorization API
HTTP Digest authorization is an important part of SIP interoperability. The Unity SIP Library provided a sophisticated authorization mechanism to control HTTP Digest negotiations after an authorization challenge.
5.7.1 Dialog
A SIP dialog maps to one-or-more SIP transactions. It is a signalling relationship between two-or-more SIP endpoints. The following fields uniquely identify SIP dialogs:
Call-ID.
The SIP address of both endpoints (To and From headers). The tag value attached to the To header.
In the SIP library, a Dialog object stores states and manages transactions on behalf of the dialog.
5.7.2 Transactions
A SIP transaction involves all messages sent between a client and a server for the purposes of completing one signalling action, such as call establishment and call termination. The dialog to which a transaction may belong and an Command Sequence identifier called CSeq uniquely identifies the transaction.
In the SIP library a transaction stores the state and manages the progress through the use of timers, event handling and state machines. A transaction can also be used outside of the context of a specific dialog to accomplish User Agent signalling action.
5.8.1 SIP URI
SIP and SIPS URIs are used for addressing. They are similar to email addresses in that they are of
