SipDeveloperGuide

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