SIP SIMPLE SDK Developer Guide

Deployment Scenarios

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

• On a LAN using Bonjour discovery mechanism for next-hop address resolution

• On the public Internet with any SIP Service provider using DNS for next-hop address resolution

• 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.

• NAT traversal is done in the end-points using ICE methodology

All topologies can be combined together in the same client application.

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

Fully featured sample programs are available in 'sipclients' package available in the 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 for Audio, IM and File Transfer

• 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_mwi - SUBSCRIBE for Voicemail Message Waiting Indicator

For a description of the sample programs see Testing

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. Blink SIP client for MacOS X available in the Mac App Store

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

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

4. SylkServer: Multiparty conference and SIP/XMPP gateway: http://sylkserver.com

Cocoa Objective C

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.

http://pyobjc.sourceforge.net/

The SDK was fully used 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 used 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 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.

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 contacts to setup the future agenda.

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

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

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.

• SIP signaling has 10 states with 16 possible transitions between them (diagram)

• 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 SIP signaling and RTP media plane

• Presence Publish/Subscribe/Notify mechanism has multiple states

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.