SipDeveloperGuide
Version 157 (Adrian Georgescu, 06/16/2011 02:53 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 | 155 | Adrian Georgescu | SIP SIMPLE client SDK is a Software Development Kit with a Python API useful for development of real-time communications end-points based on SIP and related protocols with multimedia like Audio, Instant Messaging, File Transfers, Desktop Sharing and Presence. Other media types can be easily added by using an extensible high-level API. The library has cross platform capabilities on Linux OS, Mac OSX and Microsoft Windows. The library works with no or minimal changes on any platform that supports Python and provides direct access to the input and audio devices using one of the supported backends. |
6 | 73 | Adrian Georgescu | |
7 | 155 | Adrian Georgescu | == Current Status == |
8 | 1 | Adrian Georgescu | |
9 | 155 | Adrian Georgescu | SIP SIMPLE client SDK is reliable for production use and is used today in finished products that are downloaded daily more than 300 times. The products work on Linux, Mac and Windows desktop OS and Linux Servers. |
10 | 127 | Adrian Georgescu | |
11 | 155 | Adrian Georgescu | == Installation Instructions == |
12 | 1 | Adrian Georgescu | |
13 | 155 | Adrian Georgescu | SIP SIMPLE client SDK is ready packaged for 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. 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: |
14 | 1 | Adrian Georgescu | |
15 | 155 | Adrian Georgescu | {{{ |
16 | 155 | Adrian Georgescu | sudo apt-get update |
17 | 155 | Adrian Georgescu | sudo apt-get install python-sipsimple |
18 | 155 | Adrian Georgescu | }}} |
19 | 1 | Adrian Georgescu | |
20 | 155 | Adrian Georgescu | Complete building instructions from source for the SDK and its dependencies are available [http://sipsimpleclient.com/wiki/SipInstallation here] |
21 | 1 | Adrian Georgescu | |
22 | 155 | Adrian Georgescu | == API Documentation == |
23 | 1 | Adrian Georgescu | |
24 | 155 | Adrian Georgescu | * Online documentation is available at http://sipsimpleclient.com/wiki/SipMiddlewareApi |
25 | 155 | Adrian Georgescu | * Printable documentation in PDF format is available at http://download.ag-projects.com/SipClient/SIPSIMPLE-Manual.pdf |
26 | 1 | Adrian Georgescu | |
27 | 155 | Adrian Georgescu | == Usage Instructions == |
28 | 1 | Adrian Georgescu | |
29 | 155 | Adrian Georgescu | Using SIP Simple SDK library is no different than using any other Python library, by installing it in the system manually from the source code with 'sudo python setup.py install' command or from a ready made package when available for the target OS then import its modules into the program and use it. |
30 | 1 | Adrian Georgescu | |
31 | 155 | Adrian Georgescu | To setup a simple audio call and hangup one has to write as little as 10 lines of code. A complete wide-band conferencing application has been written in only 300 lines of code. |
32 | 1 | Adrian Georgescu | |
33 | 155 | Adrian Georgescu | The complexity goes up as one may need to interact with the end-user for more actions like creating conferences interacting with telephony applications, adding chat or presence messages, this complexity is dictated by the GUI 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 achive it goal. |
34 | 1 | Adrian Georgescu | |
35 | 155 | Adrian Georgescu | === Deployment Scenarios === |
36 | 1 | Adrian Georgescu | |
37 | 155 | Adrian Georgescu | The SDK can be used to build real-time communications end-points that operates in the following scenarios: |
38 | 1 | Adrian Georgescu | |
39 | 155 | Adrian Georgescu | * On a LAN by using Bonjour discovery mechanism or on the public Internet by using the Server of a SIP Service provider, next hop lookup is based on DNS as described in RFC 3263 |
40 | 155 | Adrian Georgescu | * In a P2P overlay network like a DHT that provides routing and lookup service. For this, the SIP end-point must publish its Address of Records (AoR) address:port:protocol where it listens for incoming requests into the overlay and must implement a lookup function to obtain the peer end-points addresses from the overlay so that it can establish outbound sessions with them. For NAT traversal there must be a set of super-nodes that provide media relay functions based on ICE methodology |
41 | 1 | Adrian Georgescu | |
42 | 155 | Adrian Georgescu | == Sample Code == |
43 | 155 | Adrian Georgescu | |
44 | 155 | Adrian Georgescu | === Hello World Program === |
45 | 155 | Adrian Georgescu | |
46 | 155 | Adrian Georgescu | This is the hello world example that establish a wideband audio call. After installing the SDK, paste this code into a console and run it using Python. |
47 | 155 | Adrian Georgescu | |
48 | 155 | Adrian Georgescu | {{{ |
49 | 155 | Adrian Georgescu | #/usr/bin/python |
50 | 155 | Adrian Georgescu | |
51 | 155 | Adrian Georgescu | from application.notification import NotificationCenter |
52 | 155 | Adrian Georgescu | |
53 | 155 | Adrian Georgescu | from sipsimple.account import AccountManager |
54 | 155 | Adrian Georgescu | from sipsimple.application import SIPApplication |
55 | 155 | Adrian Georgescu | from sipsimple.core import SIPURI, ToHeader |
56 | 155 | Adrian Georgescu | from sipsimple.lookup import DNSLookup, DNSLookupError |
57 | 155 | Adrian Georgescu | from sipsimple.storage import FileStorage |
58 | 155 | Adrian Georgescu | from sipsimple.session import Session |
59 | 155 | Adrian Georgescu | from sipsimple.streams import AudioStream |
60 | 155 | Adrian Georgescu | from sipsimple.threading.green import run_in_green_thread |
61 | 155 | Adrian Georgescu | |
62 | 155 | Adrian Georgescu | from threading import Event |
63 | 155 | Adrian Georgescu | |
64 | 155 | Adrian Georgescu | class SimpleCallApplication(SIPApplication): |
65 | 155 | Adrian Georgescu | |
66 | 155 | Adrian Georgescu | def __init__(self): |
67 | 155 | Adrian Georgescu | SIPApplication.__init__(self) |
68 | 155 | Adrian Georgescu | self.ended = Event() |
69 | 155 | Adrian Georgescu | self.callee = None |
70 | 155 | Adrian Georgescu | self.session = None |
71 | 155 | Adrian Georgescu | notification_center = NotificationCenter() |
72 | 155 | Adrian Georgescu | notification_center.add_observer(self) |
73 | 155 | Adrian Georgescu | |
74 | 155 | Adrian Georgescu | def call(self, callee): |
75 | 155 | Adrian Georgescu | self.callee = callee |
76 | 155 | Adrian Georgescu | self.start(FileStorage('config')) |
77 | 155 | Adrian Georgescu | |
78 | 155 | Adrian Georgescu | @run_in_green_thread |
79 | 155 | Adrian Georgescu | def _NH_SIPApplicationDidStart(self, notification): |
80 | 155 | Adrian Georgescu | self.callee = ToHeader(SIPURI.parse(self.callee)) |
81 | 155 | Adrian Georgescu | try: |
82 | 155 | Adrian Georgescu | routes = DNSLookup().lookup_sip_proxy(self.callee.uri, ['udp']).wait() |
83 | 155 | Adrian Georgescu | except DNSLookupError, e: |
84 | 155 | Adrian Georgescu | print 'DNS lookup failed: %s' % str(e) |
85 | 155 | Adrian Georgescu | else: |
86 | 155 | Adrian Georgescu | account = AccountManager().default_account |
87 | 155 | Adrian Georgescu | self.session = Session(account) |
88 | 155 | Adrian Georgescu | self.session.connect(self.callee, routes, [AudioStream(account)]) |
89 | 155 | Adrian Georgescu | |
90 | 155 | Adrian Georgescu | def _NH_SIPSessionGotRingIndication(self, notification): |
91 | 155 | Adrian Georgescu | print 'Ringing!' |
92 | 155 | Adrian Georgescu | |
93 | 155 | Adrian Georgescu | def _NH_SIPSessionDidStart(self, notification): |
94 | 155 | Adrian Georgescu | audio_stream = notification.data.streams[0] |
95 | 155 | Adrian Georgescu | print 'Audio session established using "%s" codec at %sHz' % (audio_stream.codec, audio_stream.sample_rate) |
96 | 155 | Adrian Georgescu | |
97 | 155 | Adrian Georgescu | def _NH_SIPSessionDidFail(self, notification): |
98 | 155 | Adrian Georgescu | print 'Failed to connect' |
99 | 155 | Adrian Georgescu | self.stop() |
100 | 155 | Adrian Georgescu | |
101 | 155 | Adrian Georgescu | def _NH_SIPSessionDidEnd(self, notification): |
102 | 155 | Adrian Georgescu | print 'Session ended' |
103 | 155 | Adrian Georgescu | self.stop() |
104 | 155 | Adrian Georgescu | |
105 | 155 | Adrian Georgescu | def _NH_SIPApplicationDidEnd(self, notification): |
106 | 155 | Adrian Georgescu | self.ended.set() |
107 | 155 | Adrian Georgescu | |
108 | 155 | Adrian Georgescu | # place an audio call to the specified SIP URI in user@domain format |
109 | 155 | Adrian Georgescu | target_uri="sip:3333@sip2sip.info" |
110 | 155 | Adrian Georgescu | application = SimpleCallApplication() |
111 | 155 | Adrian Georgescu | application.call(target_uri) |
112 | 155 | Adrian Georgescu | print "Placing call to %s, press Enter to quit the program" % target_uri |
113 | 155 | Adrian Georgescu | raw_input() |
114 | 155 | Adrian Georgescu | application.session.end() |
115 | 155 | Adrian Georgescu | application.ended.wait() |
116 | 155 | Adrian Georgescu | }}} |
117 | 155 | Adrian Georgescu | |
118 | 155 | Adrian Georgescu | === Full Demo Programs === |
119 | 155 | Adrian Georgescu | |
120 | 155 | Adrian Georgescu | Full 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. These programs operate in a Linux or MacOSX terminal and implement most of the functions provided by the the SDK. |
121 | 155 | Adrian Georgescu | |
122 | 155 | Adrian Georgescu | {{{ |
123 | 155 | Adrian Georgescu | sudo apt-get install sipclients |
124 | 155 | Adrian Georgescu | }}} |
125 | 155 | Adrian Georgescu | |
126 | 155 | Adrian Georgescu | * sip-register - REGISTER a SIP end-point with a SIP Registrar or detect Bonjour neighbors |
127 | 155 | Adrian Georgescu | * sip_audio_session - Setup a single SIP audio session using RTP/sRTP media |
128 | 155 | Adrian Georgescu | * sip_session - Complete client supporting multiple sessions with Audio (RTP/sRTP), IM and File Transfer (MSRP) |
129 | 155 | Adrian Georgescu | * sip_message - Send and receive short messages in paging mode using SIP MESSAGE method |
130 | 155 | Adrian Georgescu | * sip_publish_presence- PUBLISH presence to a Presence Agent |
131 | 155 | Adrian Georgescu | * sip_subscribe_winfo - SUBSCRIBE to the watcher list for given SIP address on the Presence Agent |
132 | 155 | Adrian Georgescu | * sip_subscribe_presence - SUBSCRIBE to Presence Event for a given SIP address |
133 | 155 | Adrian Georgescu | * sip_subscribe_rls - SUBSCRIBE for Presence Event to a list managed by a Resource List Server |
134 | 155 | Adrian Georgescu | * sip_subscribe_xcap_diff - SUBSCRIBE for xcap-diff Event to monitor changes to XCAP documents |
135 | 155 | Adrian Georgescu | * sip_subscribe_mwi - SUBSCRIBE for Message Waiting Indicator |
136 | 155 | Adrian Georgescu | |
137 | 155 | Adrian Georgescu | For a description of the sample programs see http://sipsimpleclient.com/wiki/SipTesting |
138 | 155 | Adrian Georgescu | |
139 | 155 | Adrian Georgescu | === Finished Products === |
140 | 155 | Adrian Georgescu | |
141 | 155 | Adrian Georgescu | The SDK is used in several products since end of 2009. These are end-products that use the SDK and provide excellent examples for how the SDK was used to achieve the goals. |
142 | 155 | Adrian Georgescu | |
143 | 155 | Adrian Georgescu | 1. Multiparty Conference Application with Wideband Audio, IM and File Transfer: http://sylkserver.com |
144 | 155 | Adrian Georgescu | 1. SIP client implementation for MacOS X available in the Mac App Store: http://itunes.apple.com/us/app/blink-pro/id404360415?mt=12&ls=1 |
145 | 155 | Adrian Georgescu | 1. SIP Client for Linux: Blink for Ubuntu, and Debian, use same repositories from AG Projects and do 'sudo apt-get install blink' |
146 | 155 | Adrian Georgescu | 1. SIP client for MS Windows: https://blink.sipthor.net/download.phtml?download&os=nt |
147 | 155 | Adrian Georgescu | |
148 | 155 | Adrian Georgescu | == Non-Python environments == |
149 | 155 | Adrian Georgescu | |
150 | 155 | Adrian Georgescu | As the programming choice was Python this SDK will appeal to people that want to develop applications in Python. If one want to use the library into another environment it must check if is feasible or not as embedding a programming language into another is not a string forward process if at all possible. |
151 | 155 | Adrian Georgescu | |
152 | 155 | Adrian Georgescu | === Cocoa Objective C === |
153 | 155 | Adrian Georgescu | |
154 | 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. |
155 | 155 | Adrian Georgescu | |
156 | 155 | Adrian Georgescu | http://pyobjc.sourceforge.net/ |
157 | 155 | Adrian Georgescu | |
158 | 155 | Adrian Georgescu | The SDK was fully used without any problems to build Blink for MacOSX by using this bridge. |
159 | 155 | Adrian Georgescu | |
160 | 155 | Adrian Georgescu | === Qt Framework === |
161 | 155 | Adrian Georgescu | |
162 | 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. |
163 | 155 | Adrian Georgescu | |
164 | 155 | Adrian Georgescu | http://qt.nokia.com/ |
165 | 155 | Adrian Georgescu | |
166 | 155 | 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. |
167 | 155 | Adrian Georgescu | |
168 | 155 | Adrian Georgescu | === Web Browser Plugin === |
169 | 155 | Adrian Georgescu | |
170 | 155 | 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 IP 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 core software that does the media, signaling, integration with the audio device does not run in the browser itself, the browser is only used only as a GUI. |
171 | 155 | Adrian Georgescu | |
172 | 157 | 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: |
173 | 1 | Adrian Georgescu | |
174 | 157 | Adrian Georgescu | http://rtc-web.alvestrand.com. |
175 | 157 | Adrian Georgescu | |
176 | 157 | Adrian Georgescu | Google published a first specification and code drop in May 2011 and IETF and W3C had a few initial conference calls to setup the future agenda but no more at this stage. |
177 | 157 | Adrian Georgescu | |
178 | 157 | Adrian Georgescu | SIP SIMPLE Client SDK cannot run in the browser today 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. |
179 | 155 | Adrian Georgescu | |
180 | 155 | Adrian Georgescu | === C Language === |
181 | 155 | Adrian Georgescu | |
182 | 155 | Adrian Georgescu | Embedding C code into Python program is easy and feasible we do this in our Python library as well for some low level parts where we speed was needed. The other way around is not, as passing complex data structure from a high level language like Python to a low level one like C is quite a problem. How to possibly integrate Python into C is described here: |
183 | 155 | Adrian Georgescu | |
184 | 155 | Adrian Georgescu | http://docs.python.org/extending/embedding.html |
185 | 155 | Adrian Georgescu | |
186 | 155 | Adrian Georgescu | Is unlikely that the SDK can be used in such way because of data translation or multi-threading issues that could be impossible to solve, in any case nobody has ever tried. |
187 | 155 | Adrian Georgescu | |
188 | 155 | Adrian Georgescu | === Java Language === |
189 | 155 | Adrian Georgescu | |
190 | 155 | Adrian Georgescu | There is a bridge between Python and Java. |
191 | 155 | Adrian Georgescu | |
192 | 155 | Adrian Georgescu | http://www.jython.org/ |
193 | 155 | Adrian Georgescu | |
194 | 155 | Adrian Georgescu | It is unknown if is feasible to use the SDK under this environment, as nobody has reported trying it yet. |
195 | 155 | Adrian Georgescu | |
196 | 155 | Adrian Georgescu | === Translating into other languages === |
197 | 155 | Adrian Georgescu | |
198 | 155 | Adrian Georgescu | There are currently 47,000 lines of code in SIP SIMPLE Client SDK. |
199 | 155 | Adrian Georgescu | |
200 | 155 | Adrian Georgescu | The state machine for a multimedia real-time application is an order of magnitude more complex than protocols like BitTorent. |
201 | 155 | Adrian Georgescu | |
202 | 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] |
203 | 155 | Adrian Georgescu | * The RTP media used for audio and video has 6 to 10 states depending on the type of media |
204 | 155 | Adrian Georgescu | * ICE NAT traversal has many states interrelated with both signaling and the media plane |
205 | 155 | Adrian Georgescu | * IM chat functionality has multiple states |
206 | 155 | Adrian Georgescu | * Presence Subscribe/Notify mechanism has multiple states |
207 | 155 | Adrian Georgescu | |
208 | 155 | Adrian Georgescu | There are multiple-threads and the design is non-blocking by using asynchronous reactor and a notification system. SIP Simple SDK generates today 135 Notification on state changes, each of them carrying complex data structures. |
209 | 155 | Adrian Georgescu | |
210 | 155 | Adrian Georgescu | When all combined together the final application is quite complex and achieving the same in a low level programming language like C for example would be a major undertaking. Expressing this complexity into a low level language like C requires many years of work with a large team of well qualified people. |