public class SipManager extends Object
newInstance()
.
The APIs in this class allows you to:
SipSession
to get ready for making calls or listen for incoming calls. See
createSipSession()
and getSessionFor()
.open()
. Audio-only SIP calls
should be handled with a SipAudioCall
, which you can acquire with makeAudioCall()
and takeAudioCall()
.register()
and unregister()
.isOpened()
and
isRegistered()
.Note: Not all Android-powered devices support VOIP calls using
SIP. You should always call isVoipSupported()
to verify that the device supports VOIP calling and isApiSupported()
to verify that the device supports
the SIP APIs. Your application must also request the android.Manifest.permission#INTERNET
and android.Manifest.permission#USE_SIP
permissions.
For more information about using SIP, read the Session Initiation Protocol developer guide.
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_SIP_ADD_PHONE
Action string for the add-phone intent.
|
static String |
ACTION_SIP_CALL_OPTION_CHANGED
Action string for the SIP call option configuration changed intent.
|
static String |
ACTION_SIP_INCOMING_CALL
Action string for the incoming call intent for the Phone app.
|
static String |
ACTION_SIP_REMOVE_PHONE
Action string for the remove-phone intent.
|
static String |
ACTION_SIP_SERVICE_UP
Action to broadcast when SipService is up.
|
static String |
EXTRA_CALL_ID
Key to retrieve the call ID from an incoming call intent.
|
static String |
EXTRA_LOCAL_URI
Part of the ACTION_SIP_ADD_PHONE and ACTION_SIP_REMOVE_PHONE intents.
|
static String |
EXTRA_OFFER_SD
Key to retrieve the offered session description from an incoming call
intent.
|
static int |
INCOMING_CALL_RESULT_CODE
The result code to be sent back with the incoming call
PendingIntent . |
Modifier and Type | Method and Description |
---|---|
void |
close(String localProfileUri)
Closes the specified profile to not make/receive calls.
|
static Intent |
createIncomingCallBroadcast(String callId,
String sessionDescription)
Creates an incoming call broadcast intent.
|
SipSession |
createSipSession(SipProfile localProfile,
SipSession.Listener listener)
Creates a
SipSession with the specified profile. |
static String |
getCallId(Intent incomingCallIntent)
Gets the call ID from the specified incoming call broadcast intent.
|
SipProfile[] |
getListOfProfiles()
Gets the list of profiles hosted by the SIP service.
|
static String |
getOfferSessionDescription(Intent incomingCallIntent)
Gets the offer session description from the specified incoming call
broadcast intent.
|
SipSession |
getSessionFor(Intent incomingCallIntent)
Gets the
SipSession that handles the incoming call. |
static boolean |
isApiSupported(Context context)
Returns true if the SIP API is supported by the system.
|
static boolean |
isIncomingCallIntent(Intent intent)
Checks if the intent is an incoming call broadcast intent.
|
boolean |
isOpened(String localProfileUri)
Checks if the specified profile is opened in the SIP service for
making and/or receiving calls.
|
boolean |
isRegistered(String localProfileUri)
Checks if the SIP service has successfully registered the profile to the
SIP provider (specified in the profile) for receiving calls.
|
static boolean |
isSipWifiOnly(Context context)
Returns true if SIP is only available on WIFI.
|
static boolean |
isVoipSupported(Context context)
Returns true if the system supports SIP-based VOIP API.
|
SipAudioCall |
makeAudioCall(SipProfile localProfile,
SipProfile peerProfile,
SipAudioCall.Listener listener,
int timeout)
Creates a
SipAudioCall to make a call. |
SipAudioCall |
makeAudioCall(String localProfileUri,
String peerProfileUri,
SipAudioCall.Listener listener,
int timeout)
Creates a
SipAudioCall to make an audio call. |
static SipManager |
newInstance(Context context)
Creates a manager instance.
|
void |
open(SipProfile localProfile)
Opens the profile for making generic SIP calls.
|
void |
open(SipProfile localProfile,
PendingIntent incomingCallPendingIntent,
SipRegistrationListener listener)
Opens the profile for making calls and/or receiving generic SIP calls.
|
void |
register(SipProfile localProfile,
int expiryTime,
SipRegistrationListener listener)
Manually registers the profile to the corresponding SIP provider for
receiving calls.
|
void |
setRegistrationListener(String localProfileUri,
SipRegistrationListener listener)
Sets the listener to listen to registration events.
|
SipAudioCall |
takeAudioCall(Intent incomingCallIntent,
SipAudioCall.Listener listener)
Creates a
SipAudioCall to take an incoming call. |
void |
unregister(SipProfile localProfile,
SipRegistrationListener listener)
Manually unregisters the profile from the corresponding SIP provider for
stop receiving further calls.
|
public static final int INCOMING_CALL_RESULT_CODE
PendingIntent
.public static final String EXTRA_CALL_ID
public static final String EXTRA_OFFER_SD
public static final String ACTION_SIP_SERVICE_UP
public static final String ACTION_SIP_INCOMING_CALL
public static final String ACTION_SIP_ADD_PHONE
public static final String ACTION_SIP_REMOVE_PHONE
public static final String ACTION_SIP_CALL_OPTION_CHANGED
public static final String EXTRA_LOCAL_URI
public static SipManager newInstance(Context context)
context
- application context for creating the manager objectpublic static boolean isApiSupported(Context context)
public static boolean isVoipSupported(Context context)
public static boolean isSipWifiOnly(Context context)
public void open(SipProfile localProfile) throws SipException
makeAudioCall(android.net.sip.SipProfile, android.net.sip.SipProfile, android.net.sip.SipAudioCall.Listener, int)
. If one also wants to receive calls on the
profile, use
open(SipProfile, PendingIntent, SipRegistrationListener)
instead.localProfile
- the SIP profile to make calls fromSipException
- if the profile contains incorrect settings or
calling the SIP service results in an errorpublic void open(SipProfile localProfile, PendingIntent incomingCallPendingIntent, SipRegistrationListener listener) throws SipException
makeAudioCall(android.net.sip.SipProfile, android.net.sip.SipProfile, android.net.sip.SipAudioCall.Listener, int)
. If the
auto-registration option is enabled in the profile, the SIP service
will register the profile to the corresponding SIP provider periodically
in order to receive calls from the provider. When the SIP service
receives a new call, it will send out an intent with the provided action
string. The intent contains a call ID extra and an offer session
description string extra. Use getCallId(android.content.Intent)
and
getOfferSessionDescription(android.content.Intent)
to retrieve those extras.localProfile
- the SIP profile to receive incoming calls forincomingCallPendingIntent
- When an incoming call is received, the
SIP service will call
PendingIntent.send(Context, int, Intent)
to send back the
intent to the caller with INCOMING_CALL_RESULT_CODE
as the
result code and the intent to fill in the call ID and session
description information. It cannot be null.listener
- to listen to registration events; can be nullNullPointerException
- if incomingCallPendingIntent
is nullSipException
- if the profile contains incorrect settings or
calling the SIP service results in an errorgetCallId(android.content.Intent)
,
getOfferSessionDescription(android.content.Intent)
,
takeAudioCall(android.content.Intent, android.net.sip.SipAudioCall.Listener)
,
isIncomingCallIntent(android.content.Intent)
,
getCallId(android.content.Intent)
,
getOfferSessionDescription(android.content.Intent)
public void setRegistrationListener(String localProfileUri, SipRegistrationListener listener) throws SipException
open(SipProfile, PendingIntent, SipRegistrationListener)
).localProfileUri
- the URI of the profilelistener
- to listen to registration events; can be nullSipException
- if calling the SIP service results in an errorpublic void close(String localProfileUri) throws SipException
localProfileUri
- the URI of the profile to closeSipException
- if calling the SIP service results in an errorpublic boolean isOpened(String localProfileUri) throws SipException
localProfileUri
- the URI of the profile in questionSipException
- if calling the SIP service results in an errorpublic boolean isRegistered(String localProfileUri) throws SipException
isOpened(java.lang.String)
).localProfileUri
- the URI of the profile in questionSipException
- if calling the SIP service results in an errorpublic SipAudioCall makeAudioCall(SipProfile localProfile, SipProfile peerProfile, SipAudioCall.Listener listener, int timeout) throws SipException
SipAudioCall
to make a call. The attempt will be timed
out if the call is not established within timeout
seconds and
onError(SipAudioCall, SipErrorCode.TIME_OUT, String)
will be called.localProfile
- the SIP profile to make the call frompeerProfile
- the SIP profile to make the call tolistener
- to listen to the call events from SipAudioCall
;
can be nulltimeout
- the timeout value in seconds. Default value (defined by
SIP protocol) is used if timeout
is zero or negative.SipAudioCall
objectSipException
- if calling the SIP service results in an error or
VOIP API is not supported by the deviceSipAudioCall.Listener.onError(android.net.sip.SipAudioCall, int, java.lang.String)
,
isVoipSupported(android.content.Context)
public SipAudioCall makeAudioCall(String localProfileUri, String peerProfileUri, SipAudioCall.Listener listener, int timeout) throws SipException
SipAudioCall
to make an audio call. The attempt will be
timed out if the call is not established within timeout
seconds
and
onError(SipAudioCall, SipErrorCode.TIME_OUT, String)
will be called.localProfileUri
- URI of the SIP profile to make the call frompeerProfileUri
- URI of the SIP profile to make the call tolistener
- to listen to the call events from SipAudioCall
;
can be nulltimeout
- the timeout value in seconds. Default value (defined by
SIP protocol) is used if timeout
is zero or negative.SipAudioCall
objectSipException
- if calling the SIP service results in an error or
VOIP API is not supported by the deviceSipAudioCall.Listener.onError(android.net.sip.SipAudioCall, int, java.lang.String)
,
isVoipSupported(android.content.Context)
public SipAudioCall takeAudioCall(Intent incomingCallIntent, SipAudioCall.Listener listener) throws SipException
SipAudioCall
to take an incoming call. Before the call
is returned, the listener will receive a
SipAudioCall.Listener.onRinging(android.net.sip.SipAudioCall, android.net.sip.SipProfile)
callback.incomingCallIntent
- the incoming call broadcast intentlistener
- to listen to the call events from SipAudioCall
;
can be nullSipAudioCall
objectSipException
- if calling the SIP service results in an errorpublic static boolean isIncomingCallIntent(Intent intent)
intent
- the intent in questionpublic static String getCallId(Intent incomingCallIntent)
incomingCallIntent
- the incoming call broadcast intentpublic static String getOfferSessionDescription(Intent incomingCallIntent)
incomingCallIntent
- the incoming call broadcast intentpublic static Intent createIncomingCallBroadcast(String callId, String sessionDescription)
callId
- the call ID of the incoming callsessionDescription
- the session description of the incoming callpublic void register(SipProfile localProfile, int expiryTime, SipRegistrationListener listener) throws SipException
open(SipProfile, PendingIntent, SipRegistrationListener)
is
still needed to be called at least once in order for the SIP service to
notify the caller with the PendingIntent
when an incoming call is
received.localProfile
- the SIP profile to register withexpiryTime
- registration expiration time (in seconds)listener
- to listen to the registration eventsSipException
- if calling the SIP service results in an errorpublic void unregister(SipProfile localProfile, SipRegistrationListener listener) throws SipException
localProfile
- the SIP profile to register withlistener
- to listen to the registration eventsSipException
- if calling the SIP service results in an errorpublic SipSession getSessionFor(Intent incomingCallIntent) throws SipException
SipSession
that handles the incoming call. For audio
calls, consider to use SipAudioCall
to handle the incoming call.
See takeAudioCall(android.content.Intent, android.net.sip.SipAudioCall.Listener)
. Note that the method may be called only once
for the same intent. For subsequent calls on the same intent, the method
returns null.incomingCallIntent
- the incoming call broadcast intentSipException
public SipSession createSipSession(SipProfile localProfile, SipSession.Listener listener) throws SipException
SipSession
with the specified profile. Use other
methods, if applicable, instead of interacting with SipSession
directly.localProfile
- the SIP profile the session is associated withlistener
- to listen to SIP session eventsSipException
public SipProfile[] getListOfProfiles() throws SipException
SipException