SipDeveloperGuide

Version 193 (Adrian Georgescu, 06/29/2011 02:27 pm)

1 156 Adrian Georgescu
[[TOC(SipDeveloperGuide*, depth=3)]]
2 1 Adrian Georgescu
3 155 Adrian Georgescu
= SIP SIMPLE SDK Integration Guide =
4 147 Adrian Georgescu
5 163 Adrian Georgescu
SIP SIMPLE client SDK is a Software Development Kit with a Python API designed for development of real-time communications end-points based on SIP and related protocols for multimedia like Audio, Instant Messaging, File Transfers, Desktop Sharing and Presence. Other media types can be added by using an extensible high-level API. The library has cross platform capabilities on Mac OSX, Microsoft Windows and Linux OS. 
6 73 Adrian Georgescu
7 185 Adrian Georgescu
== Motivation ==
8 185 Adrian Georgescu
9 190 Adrian Georgescu
SIP protocol is peer-to-peer by nature, each peer can be either client or server depending on direction of how  session flows. The protocol can be built in end-points without the need for dedicated servers. This  makes SIP an ideal candidate for adding real-time communications to self-organizing networks where the application  runs in transitory end-points. This is not true for other protocols (e.g. XMPP) as they have a clear distinction of client and server roles which makes it unsuitable for self-organizing peer-to-peer networks. The second and most important feature is the SIP is agnostic to the type of media established between end-points. If two end-points decide to establish a certain media type over the network, no network element must understand that except for the concerned end-points themselves. For example audio is a most common media, known as VoIP, but adding another media type like chat, file transfer and desktop sharing is rather easy. As media planes, RTP (real-time protocol) and MSRP (message session relay protocol) have been defined for real time applications (e.g. audio and video) and reliable almost real-time streams (e.g IM and File Transfer) respectively. For both there are reliable NAT traversal mechanisms built-in.
10 185 Adrian Georgescu
11 193 Adrian Georgescu
== State of the Art ==
12 193 Adrian Georgescu
13 193 Adrian Georgescu
The SDK is highly innovative. While many have done in various ways bits and pieces of the functions exposed by SIP SIMPLE client SDK, this toolkit is the only one refined for developing peers without the need of servers  and contains all primitives that allows further development for additional of new functionality in a backwards compatible way.  For example, the SDK provides all primitives to offer what Skype does in an integrated way, combining audio, chat, presence and file transfer in one logical session.
14 193 Adrian Georgescu
15 155 Adrian Georgescu
== Current Status ==
16 1 Adrian Georgescu
17 180 Adrian Georgescu
SIP SIMPLE client SDK is reliable for production use and is used today in finished products that are downloaded hundreds of time per day. The products work on Linux, Mac OS, Windows desktop OS and Linux Servers.
18 127 Adrian Georgescu
19 155 Adrian Georgescu
== Installation Instructions ==
20 1 Adrian Georgescu
21 162 Adrian Georgescu
SIP SIMPLE client SDK is available as debian package for the latest Ubuntu Linux distributions (Lucid, Maverick and Natty), Debian Linux distributions (Stable and Unstable) and can be manually installed on MacOSX 10.5, 10.6 and Microsoft Windows XP, Vista and 7 by following the documentation provided with the source code.
22 1 Adrian Georgescu
23 162 Adrian Georgescu
To install the SDK on Debian or Ubuntu, configure your deb repository as described [http://www.ag-projects.com/projects-products-96/683-software-repositories here], then:
24 162 Adrian Georgescu
25 155 Adrian Georgescu
{{{
26 1 Adrian Georgescu
sudo apt-get update
27 155 Adrian Georgescu
sudo apt-get install python-sipsimple
28 155 Adrian Georgescu
}}}
29 1 Adrian Georgescu
30 162 Adrian Georgescu
Detailed building instructions from source for the SDK and its dependencies are available [http://sipsimpleclient.com/wiki/SipInstallation here] 
31 1 Adrian Georgescu
32 155 Adrian Georgescu
== API Documentation ==
33 155 Adrian Georgescu
34 1 Adrian Georgescu
 * Online documentation is available at http://sipsimpleclient.com/wiki/SipMiddlewareApi
35 1 Adrian Georgescu
 * Printable documentation in PDF format is available at http://download.ag-projects.com/SipClient/SIPSIMPLE-Manual.pdf
36 1 Adrian Georgescu
37 155 Adrian Georgescu
== Usage Instructions ==
38 1 Adrian Georgescu
39 163 Adrian Georgescu
The SDK works on any platform that supports Python and provides direct access to the input and audio devices using one of the supported backends.
40 163 Adrian Georgescu
41 171 Adrian Georgescu
Using SIP SIMPLE client SDK library is no different than using any other Python library, after installing it in the system, one must import its modules into the program and use it. There is a [http://sipsimpleclient.com/wiki/SipMiddlewareApi#SIPApplication high level API] that automates and integrates most of the tedious tasks like starting and stopping  all required sub-systems in the right order and performing most common applications like setting up an audio or a chat session so a developer can use the SDK by writing just a few lines of code without having to understand all the details or the used protocols.
42 1 Adrian Georgescu
43 178 Adrian Georgescu
To setup a simple audio call, print the connection state and hangup one has to write just a few lines of code, see Hello World example below.
44 169 Adrian Georgescu
45 184 Adrian Georgescu
A complete multi-party audio+chat+file transfer conferencing application has been written in 300 lines of code. On the other side of the scale developing a complete end-point like Skype is the most complex example of what the SDK may be used for. The complexity grows as one needs to interact with the end-user for more actions like creating conferences, interacting with telephony like applications, adding chat or handle presence updates. The complexity is dictated mainly by the external UI design, the library provides easy to understand high-level functions and the develeper does not need to understand SIP or other related protocols used inside the kit to achieve his goal.
46 1 Adrian Georgescu
47 1 Adrian Georgescu
=== Deployment Scenarios ===
48 1 Adrian Georgescu
49 155 Adrian Georgescu
The SDK can be used to build real-time communications end-points that operates in the following scenarios:
50 1 Adrian Georgescu
51 191 Adrian Georgescu
 * On a LAN using Bonjour discovery mechanism for next-hop address resolution
52 191 Adrian Georgescu
 * On the public Internet with any SIP Service provider using DNS for next-hop address resolution
53 191 Adrian Georgescu
 * Part of a P2P overlay network like a DHT that provides routing and lookup services. For this, the SIP end-point built with the SDK will publish into the P2P overlay its Address of Records (AoR) address:port:protocol where it listens for incoming requests and will implement a lookup function to obtain the peer end-point addresses from the overlay when it wants to establish an outbound session.
54 188 Adrian Georgescu
 * NAT traversal is done in the end-points using ICE methodology
55 176 Adrian Georgescu
56 176 Adrian Georgescu
All topologies can be combined together in the same client application.
57 1 Adrian Georgescu
58 155 Adrian Georgescu
== Sample Code ==
59 155 Adrian Georgescu
60 155 Adrian Georgescu
=== Hello World Program ===
61 155 Adrian Georgescu
62 164 Adrian Georgescu
This is the hello world example that establishes a wideband audio session with a test number that plays a music tune. After installing the SDK, paste this code into a console and run it using Python.
63 155 Adrian Georgescu
64 155 Adrian Georgescu
{{{
65 155 Adrian Georgescu
#/usr/bin/python
66 155 Adrian Georgescu
67 155 Adrian Georgescu
from application.notification import NotificationCenter
68 155 Adrian Georgescu
from sipsimple.account import AccountManager
69 155 Adrian Georgescu
from sipsimple.application import SIPApplication
70 155 Adrian Georgescu
from sipsimple.core import SIPURI, ToHeader
71 155 Adrian Georgescu
from sipsimple.lookup import DNSLookup, DNSLookupError
72 155 Adrian Georgescu
from sipsimple.storage import FileStorage
73 155 Adrian Georgescu
from sipsimple.session import Session
74 155 Adrian Georgescu
from sipsimple.streams import AudioStream
75 155 Adrian Georgescu
from sipsimple.threading.green import run_in_green_thread
76 155 Adrian Georgescu
from threading import Event
77 155 Adrian Georgescu
78 155 Adrian Georgescu
class SimpleCallApplication(SIPApplication):
79 155 Adrian Georgescu
80 155 Adrian Georgescu
    def __init__(self):
81 155 Adrian Georgescu
        SIPApplication.__init__(self)
82 155 Adrian Georgescu
        self.ended = Event()
83 155 Adrian Georgescu
        self.callee = None
84 155 Adrian Georgescu
        self.session = None
85 155 Adrian Georgescu
        notification_center = NotificationCenter()
86 155 Adrian Georgescu
        notification_center.add_observer(self)
87 155 Adrian Georgescu
88 155 Adrian Georgescu
    def call(self, callee):
89 155 Adrian Georgescu
        self.callee = callee
90 155 Adrian Georgescu
        self.start(FileStorage('config'))
91 155 Adrian Georgescu
92 155 Adrian Georgescu
    @run_in_green_thread
93 155 Adrian Georgescu
    def _NH_SIPApplicationDidStart(self, notification):
94 155 Adrian Georgescu
        self.callee = ToHeader(SIPURI.parse(self.callee))
95 155 Adrian Georgescu
        try:
96 155 Adrian Georgescu
            routes = DNSLookup().lookup_sip_proxy(self.callee.uri, ['udp']).wait()
97 155 Adrian Georgescu
        except DNSLookupError, e:
98 155 Adrian Georgescu
            print 'DNS lookup failed: %s' % str(e)
99 155 Adrian Georgescu
        else:
100 155 Adrian Georgescu
            account = AccountManager().default_account
101 155 Adrian Georgescu
            self.session = Session(account)
102 155 Adrian Georgescu
            self.session.connect(self.callee, routes, [AudioStream(account)])
103 155 Adrian Georgescu
104 155 Adrian Georgescu
    def _NH_SIPSessionGotRingIndication(self, notification):
105 155 Adrian Georgescu
        print 'Ringing!'
106 155 Adrian Georgescu
107 155 Adrian Georgescu
    def _NH_SIPSessionDidStart(self, notification):
108 155 Adrian Georgescu
        audio_stream = notification.data.streams[0]
109 155 Adrian Georgescu
        print 'Audio session established using "%s" codec at %sHz' % (audio_stream.codec, audio_stream.sample_rate)
110 155 Adrian Georgescu
111 155 Adrian Georgescu
    def _NH_SIPSessionDidFail(self, notification):
112 155 Adrian Georgescu
        print 'Failed to connect'
113 155 Adrian Georgescu
        self.stop()
114 155 Adrian Georgescu
115 155 Adrian Georgescu
    def _NH_SIPSessionDidEnd(self, notification):
116 155 Adrian Georgescu
        print 'Session ended'
117 155 Adrian Georgescu
        self.stop()
118 155 Adrian Georgescu
119 155 Adrian Georgescu
    def _NH_SIPApplicationDidEnd(self, notification):
120 155 Adrian Georgescu
        self.ended.set()
121 155 Adrian Georgescu
122 155 Adrian Georgescu
# place an audio call to the specified SIP URI in user@domain format
123 155 Adrian Georgescu
target_uri="sip:3333@sip2sip.info"
124 155 Adrian Georgescu
application = SimpleCallApplication()
125 1 Adrian Georgescu
application.call(target_uri)
126 155 Adrian Georgescu
print "Placing call to %s, press Enter to quit the program" % target_uri
127 155 Adrian Georgescu
raw_input()
128 1 Adrian Georgescu
application.session.end()
129 1 Adrian Georgescu
application.ended.wait()
130 1 Adrian Georgescu
}}}
131 1 Adrian Georgescu
132 1 Adrian Georgescu
=== Full Demo Programs ===
133 155 Adrian Georgescu
134 172 Adrian Georgescu
Fully featured sample programs are available in 'sipclients' package available in the [http://www.ag-projects.com/projects-products-96/683-software-repositories same repository] as python-sipsimple. 
135 1 Adrian Georgescu
136 172 Adrian Georgescu
These programs operate in a Linux or MacOSX terminal and implement most of the functions provided by the the SDK.
137 172 Adrian Georgescu
138 155 Adrian Georgescu
{{{
139 1 Adrian Georgescu
sudo apt-get install sipclients
140 155 Adrian Georgescu
}}}
141 162 Adrian Georgescu
142 1 Adrian Georgescu
 * sip-register - REGISTER a SIP end-point or detect Bonjour neighbors
143 1 Adrian Georgescu
 * sip_audio_session - Setup a single SIP audio session using RTP/sRTP media
144 172 Adrian Georgescu
 * sip_session - Complete client with multiple sessions for Audio, IM and File Transfer
145 162 Adrian Georgescu
 * sip_message - Send and receive short messages using SIP MESSAGE method
146 162 Adrian Georgescu
 * sip_publish_presence- PUBLISH presence information for a given SIP address
147 1 Adrian Georgescu
 * sip_subscribe_winfo - SUBSCRIBE to the watcher list for given SIP address
148 162 Adrian Georgescu
 * sip_subscribe_presence - SUBSCRIBE to Presence Event for a given SIP address
149 162 Adrian Georgescu
 * sip_subscribe_rls - SUBSCRIBE for Presence Event to a list of SIP addresses
150 162 Adrian Georgescu
 * sip_subscribe_mwi - SUBSCRIBE for Voicemail Message Waiting Indicator
151 155 Adrian Georgescu
152 155 Adrian Georgescu
For a description of the sample programs see http://sipsimpleclient.com/wiki/SipTesting
153 155 Adrian Georgescu
154 155 Adrian Georgescu
=== Finished Products ===
155 155 Adrian Georgescu
156 162 Adrian Georgescu
The SDK is used in several products since end of 2009. These are end-products that use the SDK and provide exhaustive examples for how the SDK was used to achieve the goals.
157 155 Adrian Georgescu
158 189 Adrian Georgescu
 1. Multimedia SIP client for MacOS X available in the Mac App Store: http://itunes.apple.com/us/app/blink-pro/id404360415?mt=12&ls=1 
159 189 Adrian Georgescu
 1. VoIP Client for Linux: Blink for Ubuntu, and Debian, use same repositories from AG Projects and do 'sudo apt-get install blink' 
160 189 Adrian Georgescu
 1. VoIP client for Windows: https://blink.sipthor.net/download.phtml?download&os=nt
161 189 Adrian Georgescu
 1. Multiparty Conference Application with Wideband Audio, IM chat and File Transfers: http://sylkserver.com
162 155 Adrian Georgescu
163 155 Adrian Georgescu
== Non-Python environments ==
164 155 Adrian Georgescu
165 189 Adrian Georgescu
As the programming choice was Python, the SDK will appeal to people that want to develop applications in Python.
166 155 Adrian Georgescu
167 173 Adrian Georgescu
If one want to use the library into another environment it must check if is feasible or not as embedding a high-level programming language into another is not a straight forward process if at all possible.
168 162 Adrian Georgescu
169 155 Adrian Georgescu
=== Cocoa Objective C ===
170 155 Adrian Georgescu
171 155 Adrian Georgescu
MacOS platform is using Objective C for native development. But it also provide a bridge between Python and Objective C. This makes it possible to write pure Python programs that run into the native OS without much changes.
172 155 Adrian Georgescu
173 155 Adrian Georgescu
http://pyobjc.sourceforge.net/
174 1 Adrian Georgescu
175 155 Adrian Georgescu
The SDK was fully used without any problems to build Blink for MacOSX by using this bridge.
176 155 Adrian Georgescu
177 155 Adrian Georgescu
=== Qt Framework ===
178 155 Adrian Georgescu
179 155 Adrian Georgescu
Qt Framework from Nokia (formerly Trolltech) is using C for native development. But it also has Python bindings. This makes it possible to write pure Python programs that integrate with Qt framework.
180 155 Adrian Georgescu
181 155 Adrian Georgescu
http://qt.nokia.com/
182 155 Adrian Georgescu
183 157 Adrian Georgescu
The SDK was fully used without any problems to build Blink for Windows and Linux by using Qt Framework and its Python bindings.
184 1 Adrian Georgescu
185 157 Adrian Georgescu
=== Web Browser Plugin ===
186 157 Adrian Georgescu
187 179 Adrian Georgescu
Today, web browsers do not give direct access to the input and output audio devices to their plugins, which is required  by a real-time audio application. Browsers do not support direct embedding of Python code either. If one looks for example at how Google Talk plugin in the browser works, it actually installs a regular server daemon into the system that performs similar functions to SIP SIMPLE Client SDK and the web browser interacts with it by using a proprietary API running on the same host between the daemon and the browser plugin. The software that handles the media, signaling, integration with the audio device does not run in the browser itself and the browser is used only as a GUI. 
188 155 Adrian Georgescu
189 155 Adrian Georgescu
There is a recent initiative to form a work group in both W3C and IETF to address this important issue of accessing and processing audio data within the browser itself as today this is not possible. This requires cooperation from the browser manufacturers, third-party developers cannot do this on their own without cooperation from the web browser makers (like Adobe has obtained for its Flash product).  This initiative is called RTCweb:
190 155 Adrian Georgescu
191 181 Adrian Georgescu
http://rtc-web.alvestrand.com
192 155 Adrian Georgescu
193 181 Adrian Georgescu
Google published a first specification and code drop in May 2011 and IETF and W3C had contacts to setup the future agenda. 
194 155 Adrian Georgescu
195 162 Adrian Georgescu
SIP SIMPLE Client SDK cannot run in the browser today for the reasons highlighted above as browsers won't support Python nor direct access to audio devices both required by the SDK to operate. However one could build a program that stays behind the browser in the same way  as Google Talk daemon does.
196 155 Adrian Georgescu
197 155 Adrian Georgescu
=== C Language  ===
198 155 Adrian Georgescu
199 170 Adrian Georgescu
How to possibly integrate Python into C is described here:
200 155 Adrian Georgescu
201 155 Adrian Georgescu
http://docs.python.org/extending/embedding.html
202 155 Adrian Georgescu
203 155 Adrian Georgescu
=== Java Language  ===
204 155 Adrian Georgescu
205 155 Adrian Georgescu
There is a bridge between Python and Java.
206 155 Adrian Georgescu
207 155 Adrian Georgescu
http://www.jython.org/
208 155 Adrian Georgescu
209 1 Adrian Georgescu
=== Translating into other languages  ===
210 158 Adrian Georgescu
211 192 Adrian Georgescu
Python is a suitable language for designing complex state machines. The state machine for a multimedia real-time application (SIP or other protocols) is orders of magnitude more complex than a near-real-time file transfer protocols like BitTorent. Real time communications imply using both signaling and media that may travel over different paths and their combined state must be aggregated in the end-points. 
212 158 Adrian Georgescu
213 155 Adrian Georgescu
 * SIP signaling has 10 states with 16 possible transitions between them, a diagram is [http://sipsimpleclient.com/raw-attachment/wiki/SipCoreApiDocumentation/sipsimple-core-invite-state-machine.png here]
214 155 Adrian Georgescu
 * RTP media used for audio and video has 6 to 10 states depending on the type of media
215 155 Adrian Georgescu
 * MSRP media used for chat functionality has multiple states
216 177 Adrian Georgescu
 * ICE NAT traversal has many states interrelated with both SIP signaling and RTP media plane
217 1 Adrian Georgescu
 * Presence Publish/Subscribe/Notify mechanism has multiple states
218 1 Adrian Georgescu
219 192 Adrian Georgescu
One must describe the transitions of states, which may contain complex data and can be raised in different threads. There are multiple sockets in use using several transports. When all combined together the final application is quite complex and achieving the SDK functionality in a low level programming language like C would be a major undertaking.