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:
-