SIP SIMPLE Client SDK

[[TOC(SipDeveloperGuide*, depth=3)]]

= SIP SIMPLE SDK Integration Guide =

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. 

== Current Status ==

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 OS, Windows desktop OS and Linux Servers.

== Installation Instructions ==

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.

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:

{{{

sudo apt-get update

sudo apt-get install python-sipsimple

}}}

Detailed building instructions from source for the SDK and its dependencies are available [http://sipsimpleclient.com/wiki/SipInstallation here] 

== API Documentation ==

There are currently 47,000 lines of code in SIP SIMPLE Client SDK. The SDK uses multiple number of threads, is non-blocking by using an asynchronous reactor and a notification system. SIP Simple SDK generates +100 notifications on state changes, each of them carrying complex data structures. Many are internal use and are not needed for using the code unless one needs granular access to individual functions of the SDK.

 * Online documentation is available at http://sipsimpleclient.com/wiki/SipMiddlewareApi

 * Printable documentation in PDF format is available at http://download.ag-projects.com/SipClient/SIPSIMPLE-Manual.pdf

== Usage Instructions ==

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.

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 that automates 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 a a VoIP call so a developer can use the SDK by writing just a few lines of code without having to understand all the details.

To setup a simple audio call, print the connection state and hangup one has to write as little as 10 lines of code. A complete audio+chat conferencing application has been written in only 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 once one needs to interact with the end-user for more actions like creating conferences, interacting with telephony like applications, adding chat or handle presence messages. 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.

=== Deployment Scenarios ===

The SDK can be used to build real-time communications end-points that operates in the following scenarios:

 * 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

 * In a P2P overlay network like a DHT that provides routing and lookup service. For this, the SIP end-point built with the SDK 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.

== Sample Code ==

=== Hello World Program ===

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.

{{{

#/usr/bin/python

from application.notification import NotificationCenter

from sipsimple.account import AccountManager

from sipsimple.application import SIPApplication

from sipsimple.core import SIPURI, ToHeader

from sipsimple.lookup import DNSLookup, DNSLookupError

from sipsimple.storage import FileStorage

from sipsimple.session import Session

from sipsimple.streams import AudioStream

from sipsimple.threading.green import run_in_green_thread

from threading import Event

class SimpleCallApplication(SIPApplication):

    def __init__(self):

        SIPApplication.__init__(self)

        self.ended = Event()

        self.callee = None

        self.session = None

        notification_center = NotificationCenter()

        notification_center.add_observer(self)

    def call(self, callee):

        self.callee = callee

        self.start(FileStorage('config'))

    @run_in_green_thread

    def _NH_SIPApplicationDidStart(self, notification):

        self.callee = ToHeader(SIPURI.parse(self.callee))

        try:

            routes = DNSLookup().lookup_sip_proxy(self.callee.uri, ['udp']).wait()

        except DNSLookupError, e:

            print 'DNS lookup failed: %s' % str(e)

        else:

            account = AccountManager().default_account

            self.session = Session(account)

            self.session.connect(self.callee, routes, [AudioStream(account)])

    def _NH_SIPSessionGotRingIndication(self, notification):

        print 'Ringing!'

    def _NH_SIPSessionDidStart(self, notification):

        audio_stream = notification.data.streams[0]

        print 'Audio session established using "%s" codec at %sHz' % (audio_stream.codec, audio_stream.sample_rate)

    def _NH_SIPSessionDidFail(self, notification):

        print 'Failed to connect'

        self.stop()

    def _NH_SIPSessionDidEnd(self, notification):

        print 'Session ended'

        self.stop()

    def _NH_SIPApplicationDidEnd(self, notification):

        self.ended.set()

# place an audio call to the specified SIP URI in user@domain format

target_uri="sip:3333@sip2sip.info"

application = SimpleCallApplication()

application.call(target_uri)

print "Placing call to %s, press Enter to quit the program" % target_uri

raw_input()

application.session.end()

application.ended.wait()

}}}

=== Full Demo Programs ===

Complete interactive 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.

{{{

sudo apt-get install sipclients

}}}

 * sip-register - REGISTER a SIP end-point or detect Bonjour neighbors

 * sip_audio_session - Setup a single SIP audio session using RTP/sRTP media

 * sip_session - Complete client with multiple sessions: Audio (RTP/sRTP), IM and File Transfer (MSRP)

 * sip_message - Send and receive short messages using SIP MESSAGE method

 * sip_publish_presence- PUBLISH presence information for a given SIP address

 * sip_subscribe_winfo - SUBSCRIBE to the watcher list for given SIP address

 * sip_subscribe_presence - SUBSCRIBE to Presence Event for a given SIP address

 * sip_subscribe_rls - SUBSCRIBE for Presence Event to a list of SIP addresses

 * sip_subscribe_xcap_diff - SUBSCRIBE for xcap-diff Event to monitor changes to policy documents

 * sip_subscribe_mwi - SUBSCRIBE for Voicemail Message Waiting Indicator

For a description of the sample programs see http://sipsimpleclient.com/wiki/SipTesting

=== Finished Products ===

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.

 1. Multiparty Conference Application with Wideband Audio, IM and File Transfer: http://sylkserver.com

 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 

 1. SIP Client for Linux: Blink for Ubuntu, and Debian, use same repositories from AG Projects and do 'sudo apt-get install blink' 

 1. SIP client for Windows: https://blink.sipthor.net/download.phtml?download&os=nt

== Non-Python environments ==

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 straight forward process if at all possible.

=== Cocoa Objective C ===

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.

http://pyobjc.sourceforge.net/

The SDK was fully used without any problems to build Blink for MacOSX by using this bridge.

=== Qt Framework ===

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.

http://qt.nokia.com/

The SDK was fully used without any problems to build Blink for Windows and Linux by using Qt Framework and its Python bindings.

=== Web Browser Plugin ===

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. 

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:

http://rtc-web.alvestrand.com. 

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. 

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.

=== C Language  ===

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:

http://docs.python.org/extending/embedding.html

=== Java Language  ===

There is a bridge between Python and Java.

http://www.jython.org/

=== Translating into other languages  ===

The state machine for a multimedia real-time application is an order of magnitude more complex than non-rela-time file transfer protocols like BitTorent.

 * 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]

 * RTP media used for audio and video has 6 to 10 states depending on the type of media

 * MSRP media used for chat functionality has multiple states

 * ICE NAT traversal has many states interrelated with both signaling and the media plane

 * Presence Publish/Subscribe/Notify mechanism has multiple states

One must describe the transitions of states which 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 same in a low level programming language like C for example would be a major undertaking. While building the SDK in Python took about 3 years, expressing this complexity into a low level language like C requires many years of work with a large team of well qualified people.