SipDeveloperGuide

Version 208 (Tijmen de Mes, 11/08/2012 12:21 pm)

1 203 Adrian Georgescu
h1. SIP SIMPLE SDK Integration Guide
2 203 Adrian Georgescu
3 203 Adrian Georgescu
4 1 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. 
5 1 Adrian Georgescu
6 1 Adrian Georgescu
7 203 Adrian Georgescu
h2. Current Status
8 203 Adrian Georgescu
9 203 Adrian Georgescu
10 1 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.
11 1 Adrian Georgescu
12 202 Adrian Georgescu
13 203 Adrian Georgescu
h2. Installation Instructions
14 203 Adrian Georgescu
15 203 Adrian Georgescu
16 1 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, 10.7 and Microsoft Windows XP, Vista and 7 by following the documentation provided with the source code.
17 1 Adrian Georgescu
18 203 Adrian Georgescu
To install the SDK on Debian or Ubuntu, configure your deb repository as described "here":http://www.ag-projects.com/projects-products-96/683-software-repositories, then:
19 1 Adrian Georgescu
20 203 Adrian Georgescu
<pre>
21 1 Adrian Georgescu
sudo apt-get update
22 1 Adrian Georgescu
sudo apt-get install python-sipsimple
23 203 Adrian Georgescu
</pre>
24 1 Adrian Georgescu
25 208 Tijmen de Mes
Detailed building instructions from source for the SDK and its dependencies are available "here":http://sipsimpleclient.ag-projects.com/projects/sipsimpleclient/wiki/SipInstallation 
26 1 Adrian Georgescu
27 1 Adrian Georgescu
28 203 Adrian Georgescu
h2. API Documentation
29 1 Adrian Georgescu
30 1 Adrian Georgescu
31 206 Tijmen de Mes
* Online documentation is available at http://sipsimpleclient.ag-projects.com/projects/sipsimpleclient/wiki/SipMiddlewareApi
32 203 Adrian Georgescu
* Printable documentation in PDF format is available at http://download.ag-projects.com/SipClient/SIPSIMPLE-Manual.pdf
33 203 Adrian Georgescu
34 203 Adrian Georgescu
35 203 Adrian Georgescu
h2. Usage Instructions
36 203 Adrian Georgescu
37 203 Adrian Georgescu
38 178 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.
39 169 Adrian Georgescu
40 208 Tijmen de Mes
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 "high level API":http://sipsimpleclient.ag-projects.com/wiki/SipMiddlewareApi#SIPApplication that automates and integrates most of the tedious tasks like starting and stopping  all required sub-systems and threads 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.
41 184 Adrian Georgescu
42 1 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.
43 1 Adrian Georgescu
44 1 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.
45 1 Adrian Georgescu
46 1 Adrian Georgescu
47 203 Adrian Georgescu
h3. Deployment Scenarios
48 203 Adrian Georgescu
49 203 Adrian Georgescu
50 1 Adrian Georgescu
The SDK can be used to build real-time communications end-points that operates in the following scenarios:
51 155 Adrian Georgescu
52 203 Adrian Georgescu
* On a LAN using Bonjour discovery mechanism for next-hop address resolution
53 203 Adrian Georgescu
* On the public Internet with any SIP Service provider using DNS for next-hop address resolution
54 203 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.
55 203 Adrian Georgescu
* NAT traversal is done in the end-points using ICE methodology
56 188 Adrian Georgescu
57 176 Adrian Georgescu
All topologies can be combined together in the same client application.
58 176 Adrian Georgescu
59 1 Adrian Georgescu
60 203 Adrian Georgescu
h2. Sample Code
61 155 Adrian Georgescu
62 203 Adrian Georgescu
63 203 Adrian Georgescu
64 203 Adrian Georgescu
h3. Hello World Program
65 203 Adrian Georgescu
66 203 Adrian Georgescu
67 155 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.
68 155 Adrian Georgescu
69 203 Adrian Georgescu
<pre>
70 155 Adrian Georgescu
#/usr/bin/python
71 155 Adrian Georgescu
72 155 Adrian Georgescu
from application.notification import NotificationCenter
73 155 Adrian Georgescu
from sipsimple.account import AccountManager
74 155 Adrian Georgescu
from sipsimple.application import SIPApplication
75 155 Adrian Georgescu
from sipsimple.core import SIPURI, ToHeader
76 155 Adrian Georgescu
from sipsimple.lookup import DNSLookup, DNSLookupError
77 155 Adrian Georgescu
from sipsimple.storage import FileStorage
78 155 Adrian Georgescu
from sipsimple.session import Session
79 155 Adrian Georgescu
from sipsimple.streams import AudioStream
80 155 Adrian Georgescu
from sipsimple.threading.green import run_in_green_thread
81 155 Adrian Georgescu
from threading import Event
82 155 Adrian Georgescu
83 155 Adrian Georgescu
class SimpleCallApplication(SIPApplication):
84 155 Adrian Georgescu
85 155 Adrian Georgescu
    def __init__(self):
86 155 Adrian Georgescu
        SIPApplication.__init__(self)
87 155 Adrian Georgescu
        self.ended = Event()
88 155 Adrian Georgescu
        self.callee = None
89 155 Adrian Georgescu
        self.session = None
90 155 Adrian Georgescu
        notification_center = NotificationCenter()
91 155 Adrian Georgescu
        notification_center.add_observer(self)
92 155 Adrian Georgescu
93 155 Adrian Georgescu
    def call(self, callee):
94 155 Adrian Georgescu
        self.callee = callee
95 155 Adrian Georgescu
        self.start(FileStorage('config'))
96 155 Adrian Georgescu
97 155 Adrian Georgescu
    @run_in_green_thread
98 155 Adrian Georgescu
    def _NH_SIPApplicationDidStart(self, notification):
99 155 Adrian Georgescu
        self.callee = ToHeader(SIPURI.parse(self.callee))
100 155 Adrian Georgescu
        try:
101 155 Adrian Georgescu
            routes = DNSLookup().lookup_sip_proxy(self.callee.uri, ['udp']).wait()
102 155 Adrian Georgescu
        except DNSLookupError, e:
103 155 Adrian Georgescu
            print 'DNS lookup failed: %s' % str(e)
104 155 Adrian Georgescu
        else:
105 155 Adrian Georgescu
            account = AccountManager().default_account
106 155 Adrian Georgescu
            self.session = Session(account)
107 155 Adrian Georgescu
            self.session.connect(self.callee, routes, [AudioStream(account)])
108 155 Adrian Georgescu
109 155 Adrian Georgescu
    def _NH_SIPSessionGotRingIndication(self, notification):
110 155 Adrian Georgescu
        print 'Ringing!'
111 1 Adrian Georgescu
112 1 Adrian Georgescu
    def _NH_SIPSessionDidStart(self, notification):
113 1 Adrian Georgescu
        audio_stream = notification.data.streams[0]
114 1 Adrian Georgescu
        print 'Audio session established using "%s" codec at %sHz' % (audio_stream.codec, audio_stream.sample_rate)
115 1 Adrian Georgescu
116 1 Adrian Georgescu
    def _NH_SIPSessionDidFail(self, notification):
117 1 Adrian Georgescu
        print 'Failed to connect'
118 1 Adrian Georgescu
        self.stop()
119 1 Adrian Georgescu
120 1 Adrian Georgescu
    def _NH_SIPSessionDidEnd(self, notification):
121 1 Adrian Georgescu
        print 'Session ended'
122 1 Adrian Georgescu
        self.stop()
123 1 Adrian Georgescu
124 172 Adrian Georgescu
    def _NH_SIPApplicationDidEnd(self, notification):
125 1 Adrian Georgescu
        self.ended.set()
126 1 Adrian Georgescu
127 1 Adrian Georgescu
# place an audio call to the specified SIP URI in user@domain format
128 1 Adrian Georgescu
target_uri="sip:3333@sip2sip.info"
129 1 Adrian Georgescu
application = SimpleCallApplication()
130 1 Adrian Georgescu
application.call(target_uri)
131 172 Adrian Georgescu
print "Placing call to %s, press Enter to quit the program" % target_uri
132 1 Adrian Georgescu
raw_input()
133 1 Adrian Georgescu
application.session.end()
134 1 Adrian Georgescu
application.ended.wait()
135 203 Adrian Georgescu
</pre>
136 1 Adrian Georgescu
137 203 Adrian Georgescu
h3. Full Demo Programs
138 1 Adrian Georgescu
139 203 Adrian Georgescu
140 203 Adrian Georgescu
Fully featured sample programs are available in 'sipclients' package available in the "same repository":http://www.ag-projects.com/projects-products-96/683-software-repositories as python-sipsimple. 
141 203 Adrian Georgescu
142 172 Adrian Georgescu
These programs operate in a Linux or MacOSX terminal and implement most of the functions provided by the the SDK.
143 162 Adrian Georgescu
144 203 Adrian Georgescu
<pre>
145 1 Adrian Georgescu
sudo apt-get install sipclients
146 203 Adrian Georgescu
</pre>
147 1 Adrian Georgescu
148 203 Adrian Georgescu
* sip-register - REGISTER a SIP end-point or detect Bonjour neighbors
149 203 Adrian Georgescu
* sip_audio_session - Setup a single SIP audio session using RTP/sRTP media
150 203 Adrian Georgescu
* sip_session - Complete client with multiple sessions for Audio, IM and File Transfer
151 203 Adrian Georgescu
* sip_message - Send and receive short messages using SIP MESSAGE method
152 203 Adrian Georgescu
* sip_publish_presence- PUBLISH presence information for a given SIP address
153 203 Adrian Georgescu
* sip_subscribe_winfo - SUBSCRIBE to the watcher list for given SIP address
154 203 Adrian Georgescu
* sip_subscribe_presence - SUBSCRIBE to Presence Event for a given SIP address
155 203 Adrian Georgescu
* sip_subscribe_rls - SUBSCRIBE for Presence Event to a list of SIP addresses
156 203 Adrian Georgescu
* sip_subscribe_mwi - SUBSCRIBE for Voicemail Message Waiting Indicator
157 1 Adrian Georgescu
158 207 Tijmen de Mes
For a description of the sample programs see http://sipsimpleclient.ag-projects.com/projects/sipsimpleclient/wiki/SipTesting
159 155 Adrian Georgescu
160 203 Adrian Georgescu
h3. Finished Products
161 203 Adrian Georgescu
162 203 Adrian Georgescu
163 173 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.
164 162 Adrian Georgescu
165 203 Adrian Georgescu
# 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 
166 203 Adrian Georgescu
# VoIP Client for Linux: Blink for Ubuntu, and Debian, use same repositories from AG Projects and do 'sudo apt-get install blink' 
167 203 Adrian Georgescu
# VoIP client for Windows: https://blink.sipthor.net/download.phtml?download&os=nt
168 203 Adrian Georgescu
# Multiparty Conference Application with Wideband Audio, IM chat and File Transfers: http://sylkserver.com
169 1 Adrian Georgescu
170 1 Adrian Georgescu
171 203 Adrian Georgescu
h2. Non-Python environments
172 203 Adrian Georgescu
173 203 Adrian Georgescu
174 196 Adrian Georgescu
As the programming choice was Python, the SDK will appeal to people that want to develop applications in Python.
175 1 Adrian Georgescu
176 1 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.
177 1 Adrian Georgescu
178 155 Adrian Georgescu
179 203 Adrian Georgescu
h3. Cocoa Objective C
180 203 Adrian Georgescu
181 203 Adrian Georgescu
182 1 Adrian Georgescu
MacOS platform is using Objective C for native development and it provides a bridge between Python and Objective C. This makes it possible to write pure Python programs that run native on the OS with minimal changes.
183 1 Adrian Georgescu
184 1 Adrian Georgescu
http://pyobjc.sourceforge.net/
185 1 Adrian Georgescu
186 1 Adrian Georgescu
The SDK was fully used to build Blink for MacOSX by using this bridge.
187 155 Adrian Georgescu
188 155 Adrian Georgescu
189 203 Adrian Georgescu
h3. Qt Framework
190 203 Adrian Georgescu
191 203 Adrian Georgescu
192 157 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.
193 157 Adrian Georgescu
194 179 Adrian Georgescu
http://qt.nokia.com/
195 155 Adrian Georgescu
196 155 Adrian Georgescu
The SDK was used to build Blink for Windows and Linux by using Qt Framework and its Python bindings.
197 155 Adrian Georgescu
198 181 Adrian Georgescu
199 203 Adrian Georgescu
h3. Web Browser Plugin
200 203 Adrian Georgescu
201 203 Adrian Georgescu
202 162 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. 
203 155 Adrian Georgescu
204 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:
205 155 Adrian Georgescu
206 170 Adrian Georgescu
http://rtc-web.alvestrand.com
207 155 Adrian Georgescu
208 155 Adrian Georgescu
Google published a first specification and code drop in May 2011 and IETF and W3C had contacts to setup the future agenda. 
209 155 Adrian Georgescu
210 155 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.
211 155 Adrian Georgescu
212 155 Adrian Georgescu
213 203 Adrian Georgescu
h3. C Language 
214 203 Adrian Georgescu
215 203 Adrian Georgescu
216 1 Adrian Georgescu
How to possibly integrate Python into C is described here:
217 158 Adrian Georgescu
218 198 Adrian Georgescu
http://docs.python.org/extending/embedding.html
219 158 Adrian Georgescu
220 155 Adrian Georgescu
221 203 Adrian Georgescu
h3. Java Language 
222 203 Adrian Georgescu
223 203 Adrian Georgescu
224 1 Adrian Georgescu
There is a bridge between Python and Java.
225 1 Adrian Georgescu
226 198 Adrian Georgescu
http://www.jython.org/
227 1 Adrian Georgescu
228 1 Adrian Georgescu
229 203 Adrian Georgescu
h3. Translating into other languages 
230 203 Adrian Georgescu
231 203 Adrian Georgescu
232 1 Adrian Georgescu
Python is a suitable high-level 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. 
233 1 Adrian Georgescu
234 208 Tijmen de Mes
* SIP signaling has 10 states with 16 possible transitions between them, a diagram is "here":http://sipsimpleclient.ag-projects.com/raw-attachment/wiki/SipCoreApiDocumentation/sipsimple-core-invite-state-machine.png
235 203 Adrian Georgescu
* RTP media used for audio and video has 6 to 10 states depending on the type of media
236 203 Adrian Georgescu
* MSRP media used for chat functionality has multiple states
237 203 Adrian Georgescu
* ICE NAT traversal has many states interrelated with both SIP signaling and RTP media plane
238 203 Adrian Georgescu
* Presence Publish/Subscribe/Notify mechanism has multiple states
239 1 Adrian Georgescu
240 1 Adrian Georgescu
There are +40K lines of code in the SDK.  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 and one must take care the no task can block another. 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.