SipDeveloperGuide

Version 213 (Adrian Georgescu, 03/29/2013 10:44 am)

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