Exploring Android SDK Support for SIP

The SIP APIs introduced in Android 2.3 (API Level 9) enable developers to write all sorts of new applications. SIP is the driving protocol behind VoIP (Voice over IP) softphone applications (Skype-style).

What Is Session Initiation Protocol (SIP)?

Session Initiation Protocol, or SIP, is a protocol for text, voice and video communication over the network. SIP communication operates very similarly to the HTTP request and response model.

For more of the technical details, you might want to check out Webopedia's SIP page or peruse the RFC-3261 standard. Be aware that the SIP API takes care of most of the details. As with any protocol, having some familiarity helps, though.

Why Would I Use the Android SIP API?

SIP can be used to build applications that include voice calling, with little additional effort. Imagine creating a shopping application with a direct calling feature. Without leaving the app. Without using any of the users minutes or even requiring that they're on a phone (tablet, TV?). Or an app with voice support provided inside the app itself. Imagine easily adding voice chat to a game. Or a news reader where readers can connect and discuss what they're reading. It can be used to turn just about any Android device -- or app -- into a smart-softphone, as it were.

The SIP APIs will likely become more popular and more widely used as Android devices grow beyond smartphone markets and traditional telephony features are not always guaranteed on a given device (e.g. tablets, TVs, etc.).

What Android Devices Support SIP?

The SIP APIs were not introduced until Android 2.3, so you'll want to target only devices running API Level 9 or higher in your application's Android manifest file.

<uses-sdk android:minSdkVersion="9" />

That said, not all devices have SIP capabilities; only a subset do. Therefore, you'll need to add a filter in your Android manifest file to specify that SIP is required by your application (and thus will be filtered appropriately by the Android Market).

<uses-feature android:name="android.hardware.sip.voip" />

At minimum, you'll also need to add two permissions to your application in order to access SIP device features and the internet in general:

<uses-permission android:name="android.permission.USE_SIP" />

<uses-permission android:name="android.permission.INTERNET" />

If your application uses the SIP APIs to make audio calls, you'll likely also need the following permissions for working with audio on the device:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Programmatically, you should also check at runtime before using any SIP and VoIP device features using the SipManager.isVoipSupported() and the SipManager.isApiSupported() static methods.

How Do I Get Started with SIP in Android?

You'll find all the SIP-related Android classes in the android.net.sip package. Within the Android scope, SIP communication begins with the SipManager class (android.net.sip.SipManager). The SipManager class is used to access SIP services, create sessions and verify connectivity. In order to create a SipSession (android.net.sip.SipSession), you're going to need to configure the Sip Profile for each call participant and tie it to the session. Once you've got your profile, you're ready to create the session and initiate a call or accept an incoming one.

How Do I Configure an Android SIP Profile?

Before you can communicate with others via SIP, each user needs a SIP account. There are lots of SIP account providers out there. Wikipedia lists a few. Asterisk, the PBX software, is compatible with SIP.

The Android SIP APIs include a class called SipProfile (android.net.sip.SipProfile), which you can use to configure a user's SIP account information. There's a helpful builder class to facilitate configuration called SipProfile.Builder (android.net.sip.SipProfile.Builder) that you may want to use.

How Do I Make an Audio Call Using the Android SIP APIs?

In brief, once you've got valid SipProfile instances for each end of a call, you can use the SipAudioCall class and the SipManager.makeAudioCall() method to initiate an audio call. All audio call details are then managed within the SipAudioCall class, including such things as startAudio() and sendDtmf() type commands. However, you don't make any such calls until after you receive the appropriate callbacks to your SipAudioCall.Listener class.

What About Other Types of SIP Communication, like Video?

While there's a helper class for audio calls, you can use the open() and close() methods of the SipManager class to initiate other types of SIP communication, like text or video sessions. You'll have to provide the bi-directional streaming, though.

How Do I Test My Android SIP Application?

You must test SIP features using a physical device; the Android emulator is not capable of emulating a SIP-based session. Therefore, you'll need a few SIP-aware Android devices running Android 2.3 or later, such as the Nexus One, Nexus S, and several other devices, for testing purposes.

Where Can I Find Sample Applications That Showcase the SIP APIs?

The Android guys and gals have included a sample application called SipDemo that is available for your review. The application is a simple audio-based walkie-talkie application using SIP. We suggest reviewing the application source code as it demonstrates SIP API best practices as well as how to configure your Android manifest file to support SIP and filter out devices that do not support SIP.

Conclusion

Beginning with Android 2.3 (API Level 9), developers can incorporate exciting internet telephony features into their Android applications using the Android SIP APIs. Testing SIP-based applications can be a little tricky, since you must test on physical devices. What types of SIP-based applications are you hoping to see developed in the near future? Are you thinking of developing one yourself? Let us know!

About the Authors

Shane Conder and Lauren Darcey--Contributing Editors, Mobile Development--have coauthored two books on Android development: an in-depth programming book entitled Android Wireless Application Development (ISBN-13: 978-0-321-62709-4) and Sams Teach Yourself Android Application Development in 24 Hours (ISBN-13: 978-0-321-67335-0). When not writing, they spend their time developing mobile software at their company and providing consulting services.         Email        |        Blog        |        Twitter