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:
Here are the requirements for developing a SIP application:
Here is a summary of the classes and one interface
(SipRegistrationListener) that are included in the Android SIP
API:
| Class/Interface | Description |
|---|---|
| {@link android.net.sip.SipAudioCall} | Handles an Internet audio call over SIP. |
| {@link android.net.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"). |
| {@link android.net.sip.SipErrorCode} | Defines error codes returned during SIP actions. |
| {@link android.net.sip.SipManager} | Provides APIs for SIP tasks, such as initiating SIP connections, and provides access to related SIP services. |
| {@link android.net.sip.SipProfile} | Defines a SIP profile, including a SIP account, domain and server information. |
| {@link android.net.sip.SipProfile.Builder} | Helper class for creating a SipProfile. |
| {@link android.net.sip.SipSession} | Represents a SIP session that is associated with a SIP dialog or a standalone transaction not within a dialog. |
| {@link android.net.sip.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"). |
| {@link android.net.sip.SipSession.State} | Defines SIP session states, such as "registering", "outgoing call", and "in call". |
| {@link android.net.sip.SipRegistrationListener} | An interface that is a listener for SIP registration events. |
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_SIPandroid.permission.INTERNETTo 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, in Android Market), 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 ({@link android.content.BroadcastReceiver} subclass) in the application's manifest:
<receiver android:name=".IncomingCallReceiver" android:label="Call Receiver"/>Here are excerpts from the SipDemo manifest:
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
package="com.example.android.sip">
...
<receiver android:name=".IncomingCallReceiver" android:label="Call Receiver"/>
...
<uses-sdk android:minSdkVersion="9" />
<uses-permission android:name="android.permission.USE_SIP" />
<uses-permission android:name="android.permission.INTERNET" />
...
<uses-feature android:name="android.hardware.sip.voip" android:required="true" />
<uses-feature android:name="android.hardware.wifi" android:required="true" />
<uses-feature android:name="android.hardware.microphone" android:required="true" />
</manifest>
To use the SIP API, your application must create a {@link android.net.sip.SipManager} object. The {@link android.net.sip.SipManager} takes care of the following in your application:
You instantiate a new {@link android.net.sip.SipManager} as follows:
public SipManager mSipManager = null;
...
if(mSipManager == null) {
mSipManager = SipManager.newInstance(this);
}
A typical Android SIP application involves one or more users, each of whom has a SIP account. In an Android SIP application, each SIP account is represented by a {@link android.net.sip.SipProfile} object.
A {@link android.net.sip.SipProfile} defines a SIP profile, including a SIP account, and domain and server information. The profile associated with the SIP account on the device running the application is called the local profile. The profile that the session is connected to is called the peer profile. When your SIP application logs into the SIP server with the local {@link android.net.sip.SipProfile}, this effectively registers the device as the location to send SIP calls to for your SIP address.
This section shows how to create a {@link android.net.sip.SipProfile}, register it with a SIP server, and track registration events.
You create a {@link android.net.sip.SipProfile} object as follows:
public SipProfile mSipProfile = null; ... SipProfile.Builder builder = new SipProfile.Builder(username, domain); builder.setPassword(password); mSipProfile = builder.build();
The following code excerpt opens the local profile for making calls and/or
receiving generic SIP calls. The caller can make subsequent calls through
mSipManager.makeAudioCall. This excerpt also sets the action
android.SipDemo.INCOMING_CALL, which will be used by an intent
filter when the device receives a call (see Setting up
an intent filter to receive calls). This is the registration step:
Intent intent = new Intent();
intent.setAction("android.SipDemo.INCOMING_CALL");
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA);
mSipManager.open(mSipProfile, pendingIntent, null);
Finally, this code sets a SipRegistrationListener on the {@link
android.net.sip.SipManager}. This tracks whether the {@link
android.net.sip.SipProfile} was successfully registered with your SIP service
provider:
mSipManager.setRegistrationListener(mSipProfile.getUriString(), new SipRegistrationListener() {
public void onRegistering(String localProfileUri) {
updateStatus("Registering with SIP Server...");
}
public void onRegistrationDone(String localProfileUri, long expiryTime) {
updateStatus("Ready");
}
public void onRegistrationFailed(String localProfileUri, int errorCode,
String errorMessage) {
updateStatus("Registration failed. Please check settings.");
}
When your application is done using a profile, it should close it to free associated objects into memory and unregister the device from the server. For example:
public void closeLocalProfile() {
if (mSipManager == null) {
return;
}
try {
if (mSipProfile != null) {
mSipManager.close(mSipProfile.getUriString());
}
} catch (Exception ee) {
Log.d("WalkieTalkieActivity/onDestroy", "Failed to close local profile.", ee);
}
}
To make an audio call, you must have the following in place:
To make an audio call, you should set up a {@link android.net.sip.SipAudioCall.Listener}. Much of the client's interaction with the SIP stack happens through listeners. In this snippet, you see how the {@link android.net.sip.SipAudioCall.Listener} sets things up after the call is established:
SipAudioCall.Listener listener = new SipAudioCall.Listener() {
@Override
public void onCallEstablished(SipAudioCall call) {
call.startAudio();
call.setSpeakerMode(true);
call.toggleMute();
...
}
@Override
public void onCallEnded(SipAudioCall call) {
// Do something.
}
};
Once you've set up the {@link android.net.sip.SipAudioCall.Listener}, you can
make the call. The {@link android.net.sip.SipManager} method
makeAudioCall takes the following parameters:
null,
but as shown above, the listener is used to set things up once the call is
established.For example:
call = mSipManager.makeAudioCall(mSipProfile.getUriString(), sipAddress, listener, 30);
To receive calls, a SIP application must include a subclass of {@link android.content.BroadcastReceiver} that has the ability to respond to an intent indicating that there is an incoming call. Thus, you must do the following in your application:
AndroidManifest.xml, declare a
<receiver>. In SipDemo, this is
<receiver android:name=".IncomingCallReceiver"
android:label="Call Receiver"/>.IncomingCallReceiver.android.SipDemo.INCOMING_CALL. To receive calls, your SIP application must subclass {@link
android.content.BroadcastReceiver}. The
Android system handles incoming SIP calls and broadcasts an "incoming
call" intent (as defined by the application) when it receives
a call. Here is the subclassed {@link android.content.BroadcastReceiver}
code from SipDemo. To see the full example, go to SipDemo sample, which
is included in the SDK samples. For information on downloading and installing
the SDK samples, see
Getting the Samples.
/*** Listens for incoming SIP calls, intercepts and hands them off to WalkieTalkieActivity.
*/
public class IncomingCallReceiver extends BroadcastReceiver {
/**
* Processes the incoming call, answers it, and hands it over to the
* WalkieTalkieActivity.
* @param context The context under which the receiver is running.
* @param intent The intent being received.
*/
@Override
public void onReceive(Context context, Intent intent) {
SipAudioCall incomingCall = null;
try {
SipAudioCall.Listener listener = new SipAudioCall.Listener() {
@Override
public void onRinging(SipAudioCall call, SipProfile caller) {
try {
call.answerCall(30);
} catch (Exception e) {
e.printStackTrace();
}
}
};
WalkieTalkieActivity wtActivity = (WalkieTalkieActivity) context;
incomingCall = wtActivity.mSipManager.takeAudioCall(intent, listener);
incomingCall.answerCall(30);
incomingCall.startAudio();
incomingCall.setSpeakerMode(true);
if(incomingCall.isMuted()) {
incomingCall.toggleMute();
}
wtActivity.call = incomingCall;
wtActivity.updateStatus(incomingCall);
} catch (Exception e) {
if (incomingCall != null) {
incomingCall.close();
}
}
}
}
When the SIP service receives a new call, it sends out an intent with the
action string provided by the application. In SipDemo, this action string is
android.SipDemo.INCOMING_CALL.
This code excerpt from SipDemo shows how the {@link
android.net.sip.SipProfile} object gets created with a pending intent based on
the action string android.SipDemo.INCOMING_CALL. The
PendingIntent object will perform a broadcast when the {@link
android.net.sip.SipProfile} receives a call:
public SipManager mSipManager = null;
public SipProfile mSipProfile = null;
...
Intent intent = new Intent();
intent.setAction("android.SipDemo.INCOMING_CALL");
PendingIntent pendingIntent = PendingIntent.getBroadcast(this, 0, intent, Intent.FILL_IN_DATA);
mSipManager.open(mSipProfile, pendingIntent, null);
The broadcast will be intercepted by the intent filter, which will then fire
the receiver (IncomingCallReceiver). You can specify an intent
filter in your application's manifest file, or do it in code as in the SipDemo
sample application's onCreate() method
of the application's Activity:
public class WalkieTalkieActivity extends Activity implements View.OnTouchListener {
...
public IncomingCallReceiver callReceiver;
...
@Override
public void onCreate(Bundle savedInstanceState) {
IntentFilter filter = new IntentFilter();
filter.addAction("android.SipDemo.INCOMING_CALL");
callReceiver = new IncomingCallReceiver();
this.registerReceiver(callReceiver, filter);
...
}
...
}
To test SIP applications, you need the following:
To test a SIP application: