Session Initiation Protocol for Android

Session Initiation Protocol for Android

Android provides an API that supports the Session Initiation Protocol (SIP). This lets you add SIP-based internet telephony features to your applications. Android includes a full SIP protocol stack and integrated call management services that let applications easily set up outgoing and incoming voice calls, without having to manage sessions, transport-level communication, or audio record or playback directly.

Here are examples of the types of applications that might use the SIP API:

Video conferencing.

Instant messaging.

Requirements and Limitations

Here are the requirements for developing a SIP application:

You must have a mobile device that is running Android 2.3 or higher.

SIP runs over a wireless data connection, so your device must have a data connection (with a mobile data service or Wi-Fi). This means that you can't test on AVD—you can only test on a physical device. For details, see Testing SIP Applications.

Each participant in the application's communication session must have a SIP account. There are many different SIP providers that offer SIP accounts.

SIP API Classes and Interfaces

Here is a summary of the classes and one interface (SipRegistrationListener) that are included in the Android SIP API:

Class/Interface Description

SipAudioCall Handles an Internet audio call over SIP.

SipAudioCall.Listener Listener for events relating to a SIP call, such as when a call is being received ("on ringing") or a call is outgoing ("on calling").

SipErrorCode Defines error codes returned during SIP actions.

SipManager Provides APIs for SIP tasks, such as initiating SIP connections, and provides access to related SIP services.

SipProfile Defines a SIP profile, including a SIP account, domain and server information.

SipProfile.Builder Helper class for creating a SipProfile.

SipSession Represents a SIP session that is associated with a SIP dialog or a standalone transaction not within a dialog.

SipSession.Listener Listener for events relating to a SIP session, such as when a session is being registered ("on registering") or a call is outgoing ("on calling").

SipSession.State Defines SIP session states, such as "registering", "outgoing call", and "in call".

SipRegistrationListener An interface that is a listener for SIP registration events.

Creating the Manifest

If you are developing an application that uses the SIP API, remember that the feature is supported only on Android 2.3 (API level 9) and higher versions of the platform. Also, among devices running Android 2.3 (API level 9) or higher, not all devices will offer SIP support.

To use SIP, add the following permissions to your application's manifest:

android.permission.USE_SIP

android.permission.INTERNET

To ensure that your application can only be installed on devices that are capable of supporting SIP, add the following to your application's manifest:

<uses-sdk android:minSdkVersion="9" />. This indicates that your application requires Android 2.3 or higher. For more information, see API Levels and the documentation for the <uses-sdk> element.

To control how your application is filtered from devices that do not support SIP (for example, on Google Play), add the following to your application's manifest:

<uses-feature android:name="android.hardware.sip.voip" />. This states that your application uses the SIP API. The declaration should include an android:required attribute that indicates whether you want the application to be filtered from devices that do not offer SIP support. Other <uses-feature> declarations may also be needed, depending on your implementation. For more information, see the documentation for the <uses- feature> element.

If your application is designed to receive calls, you must also define a receiver (BroadcastReceiver subclass) in the application's manifest: