Android APIs
public class

SipAudioCall

extends Object
java.lang.Object
   ↳ android.net.sip.SipAudioCall

Class Overview

Handles an Internet audio call over SIP. You can instantiate this class with SipManager, using makeAudioCall() and takeAudioCall().

Note: Using this class require the INTERNET and USE_SIP permissions. In addition, startAudio() requires the RECORD_AUDIO, ACCESS_WIFI_STATE, and WAKE_LOCK permissions; and setSpeakerMode() requires the MODIFY_AUDIO_SETTINGS permission.

Developer Guides

For more information about using SIP, read the Session Initiation Protocol developer guide.

Summary

Nested Classes
class SipAudioCall.Listener Listener for events relating to a SIP call, such as when a call is being recieved ("on ringing") or a call is outgoing ("on calling"). 
Public Constructors
SipAudioCall(Context context, SipProfile localProfile)
Creates a call object with the local SIP profile.
Public Methods
void answerCall(int timeout)
Answers a call.
void attachCall(SipSession session, String sessionDescription)
Attaches an incoming call to this call object.
void close()
Closes this object.
void continueCall(int timeout)
Continues a call that's on hold.
void endCall()
Ends a call.
SipProfile getLocalProfile()
Gets the local SIP profile.
SipProfile getPeerProfile()
Gets the peer's SIP profile.
int getState()
Gets the state of the SipSession that carries this call.
void holdCall(int timeout)
Puts a call on hold.
boolean isInCall()
Checks if the call is established.
boolean isMuted()
Checks if the call is muted.
boolean isOnHold()
Checks if the call is on hold.
void makeCall(SipProfile peerProfile, SipSession sipSession, int timeout)
Initiates an audio call to the specified profile.
void sendDtmf(int code, Message result)
Sends a DTMF code.
void sendDtmf(int code)
Sends a DTMF code.
void setListener(SipAudioCall.Listener listener)
Sets the listener to listen to the audio call events.
void setListener(SipAudioCall.Listener listener, boolean callbackImmediately)
Sets the listener to listen to the audio call events.
void setSpeakerMode(boolean speakerMode)
Puts the device to speaker mode.
void startAudio()
Starts the audio for the established call.
void toggleMute()
Toggles mute.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public SipAudioCall (Context context, SipProfile localProfile)

Added in API level 9

Creates a call object with the local SIP profile.

Parameters
context the context for accessing system services such as ringtone, audio, WIFI etc

Public Methods

public void answerCall (int timeout)

Added in API level 9

Answers 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.

Parameters
timeout the timeout value in seconds. Default value (defined by SIP protocol) is used if timeout is zero or negative.
Throws
SipException if the SIP service fails to answer the call
See Also

public void attachCall (SipSession session, String sessionDescription)

Added in API level 9

Attaches an incoming call to this call object.

Parameters
session the session that receives the incoming call
sessionDescription the session description of the incoming call
Throws
SipException if the SIP service fails to attach this object to the session or VOIP API is not supported by the device
See Also

public void close ()

Added in API level 9

Closes this object. This object is not usable after being closed.

public void continueCall (int timeout)

Added in API level 9

Continues a call that's on hold. When succeeds, onCallEstablished(SipAudioCall) is called. 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.

Parameters
timeout the timeout value in seconds. Default value (defined by SIP protocol) is used if timeout is zero or negative.
Throws
SipException if the SIP service fails to unhold the call
See Also

public void endCall ()

Added in API level 9

Ends a call.

Throws
SipException if the SIP service fails to end the call

public SipProfile getLocalProfile ()

Added in API level 9

Gets the local SIP profile.

Returns
  • the local SIP profile

public SipProfile getPeerProfile ()

Added in API level 9

Gets the peer's SIP profile.

Returns
  • the peer's SIP profile

public int getState ()

Added in API level 9

Gets the state of the SipSession that carries this call. The value returned must be one of the states in SipSession.State.

Returns
  • the session state

public void holdCall (int timeout)

Added in API level 9

Puts a call on hold. When succeeds, onCallHeld(SipAudioCall) is called. 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.

Parameters
timeout the timeout value in seconds. Default value (defined by SIP protocol) is used if timeout is zero or negative.
Throws
SipException if the SIP service fails to hold the call
See Also

public boolean isInCall ()

Added in API level 9

Checks if the call is established.

Returns
  • true if the call is established

public boolean isMuted ()

Added in API level 9

Checks if the call is muted.

Returns
  • true if the call is muted

public boolean isOnHold ()

Added in API level 9

Checks if the call is on hold.

Returns
  • true if the call is on hold

public void makeCall (SipProfile peerProfile, SipSession sipSession, int timeout)

Added in API level 9

Initiates an audio call to the specified profile. 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.

Parameters
peerProfile the SIP profile to make the call to
sipSession the SipSession for carrying out the call
timeout the timeout value in seconds. Default value (defined by SIP protocol) is used if timeout is zero or negative.
Throws
SipException if the SIP service fails to create a session for the call or VOIP API is not supported by the device
See Also

public void sendDtmf (int code, Message result)

Added in API level 9

Sends a DTMF code. According to RFC 2883, event 0--9 maps to decimal value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event flash to 16. Currently, event flash is not supported.

Parameters
code the DTMF code to send. Value 0 to 15 (inclusive) are valid inputs.
result the result message to send when done

public void sendDtmf (int code)

Added in API level 9

Sends a DTMF code. According to RFC 2883, event 0--9 maps to decimal value 0--9, '*' to 10, '#' to 11, event 'A'--'D' to 12--15, and event flash to 16. Currently, event flash is not supported.

Parameters
code the DTMF code to send. Value 0 to 15 (inclusive) are valid inputs.

public void setListener (SipAudioCall.Listener listener)

Added in API level 9

Sets the listener to listen to the audio call events. The method calls setListener(listener, false).

Parameters
listener to listen to the audio call events of this object
See Also

public void setListener (SipAudioCall.Listener listener, boolean callbackImmediately)

Added in API level 9

Sets the listener to listen to the audio call events. A SipAudioCall can only hold one listener at a time. Subsequent calls to this method override the previous listener.

Parameters
listener to listen to the audio call events of this object
callbackImmediately set to true if the caller wants to be called back immediately on the current state

public void setSpeakerMode (boolean speakerMode)

Added in API level 9

Puts the device to speaker mode.

Note: Requires the MODIFY_AUDIO_SETTINGS permission.

Parameters
speakerMode set true to enable speaker mode; false to disable

public void startAudio ()

Added in API level 9

Starts the audio for the established call. This method should be called after onCallEstablished(SipAudioCall) is called.

Note: Requires the RECORD_AUDIO, ACCESS_WIFI_STATE and WAKE_LOCK permissions.

public void toggleMute ()

Added in API level 9

Toggles mute.