Call

public final class Call
extends Object

java.lang.Object
   ↳ android.telecom.Call


Represents an ongoing phone call that the in-call app should present to the user.

Summary

Nested classes

class Call.Callback

Defines callbacks which inform the InCallService of changes to a Call

class Call.Details

 

class Call.RttCall

A class that holds the state that describes the state of the RTT channel to the remote party, if it is active. 

Constants

String AVAILABLE_PHONE_ACCOUNTS

The key to retrieve the optional PhoneAccounts Telecom can bundle with its Call extras.

String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC) when the last outgoing emergency call was made.

int STATE_ACTIVE

The state of a Call when actively supporting conversation.

int STATE_CONNECTING

The initial state of an outgoing Call.

int STATE_DIALING

The state of an outgoing Call when dialing the remote number, but not yet connected.

int STATE_DISCONNECTED

The state of a Call when no further voice or other communication is being transmitted, the remote side has been or will inevitably be informed that the Call is no longer active, and the local data transport has or inevitably will release resources associated with this Call.

int STATE_DISCONNECTING

The state of a Call when the user has initiated a disconnection of the call, but the call has not yet been disconnected by the underlying ConnectionService.

int STATE_HOLDING

The state of a Call when in a holding state.

int STATE_NEW

The state of a Call when newly created.

int STATE_PULLING_CALL

The state of an external call which is in the process of being pulled from a remote device to the local device.

int STATE_RINGING

The state of an incoming Call when ringing locally, but not yet connected.

int STATE_SELECT_PHONE_ACCOUNT

The state of an outgoing Call when waiting on user to select a PhoneAccount through which to place the call.

Public methods

void answer(int videoState)

Instructs this STATE_RINGING Call to answer.

void conference(Call callToConferenceWith)

Instructs this Call to enter a conference.

void deflect(Uri address)

Instructs this STATE_RINGING Call to deflect.

void disconnect()

Instructs this Call to disconnect.

List<String> getCannedTextResponses()

Obtains a list of canned, pre-configured message responses to present to the user as ways of rejecting this Call using via a text message.

List<Call> getChildren()

Obtains the children of this conference Call, if any.

List<Call> getConferenceableCalls()

Returns the list of Calls with which this Call is allowed to conference.

Call.Details getDetails()

Obtains an object containing call details.

Call getParent()

Obtains the parent of this Call in a conference, if any.

String getRemainingPostDialSequence()

Obtains the post-dial sequence remaining to be emitted by this Call, if any.

Call.RttCall getRttCall()

Returns this call's RttCall object.

int getState()

Obtains the state of this Call.

InCallService.VideoCall getVideoCall()

Obtains an object that can be used to display video from this Call.

void handoverTo(PhoneAccountHandle toHandle, int videoState, Bundle extras)

Initiates a handover of this Call to the ConnectionService identified by toHandle.

void hold()

Instructs this Call to go on hold.

boolean isRttActive()

Returns whether this call has an active RTT connection.

void mergeConference()

Merges the calls within this conference.

void phoneAccountSelected(PhoneAccountHandle accountHandle, boolean setDefault)

Notifies this Call that an account has been selected and to proceed with placing an outgoing call.

void playDtmfTone(char digit)

Instructs this Call to play a dual-tone multi-frequency signaling (DTMF) tone.

void postDialContinue(boolean proceed)

Instructs this Call to continue playing a post-dial DTMF string.

void pullExternalCall()

Initiates a request to the ConnectionService to pull an external call to the local device.

void putExtras(Bundle extras)

Adds some extras to this Call.

void registerCallback(Call.Callback callback)

Registers a callback to this Call.

void registerCallback(Call.Callback callback, Handler handler)

Registers a callback to this Call.

void reject(boolean rejectWithMessage, String textMessage)

Instructs this STATE_RINGING Call to reject.

void removeExtras(List<String> keys)

Removes extras from this Call.

void removeExtras(String... keys)

Removes extras from this Call.

void respondToRttRequest(int id, boolean accept)

Responds to an RTT request received via the onRttRequest(Call, int) )} callback.

void sendCallEvent(String event, Bundle extras)

Sends a Call event from this Call to the associated Connection in the ConnectionService.

void sendRttRequest()

Sends an RTT upgrade request to the remote end of the connection.

void splitFromConference()

Instructs this Call to split from any conference call with which it may be connected.

void stopDtmfTone()

Instructs this Call to stop any dual-tone multi-frequency signaling (DTMF) tone currently playing.

void stopRtt()

Terminate the RTT session on this call.

void swapConference()

Swaps the calls within this conference.

String toString()

Returns a string representation of the object.

void unhold()

Instructs this STATE_HOLDING call to release from hold.

void unregisterCallback(Call.Callback callback)

Unregisters a callback from this Call.

Inherited methods

Constants

AVAILABLE_PHONE_ACCOUNTS

added in API level 23
String AVAILABLE_PHONE_ACCOUNTS

The key to retrieve the optional PhoneAccounts Telecom can bundle with its Call extras. Used to pass the phone accounts to display on the front end to the user in order to select phone accounts to (for example) place a call.

Constant Value: "selectPhoneAccountAccounts"

EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

added in API level 26
String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

Extra key used to indicate the time (in milliseconds since midnight, January 1, 1970 UTC) when the last outgoing emergency call was made. This is used to identify potential emergency callbacks.

Constant Value: "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS"

STATE_ACTIVE

added in API level 23
int STATE_ACTIVE

The state of a Call when actively supporting conversation.

Constant Value: 4 (0x00000004)

STATE_CONNECTING

added in API level 23
int STATE_CONNECTING

The initial state of an outgoing Call. Common transitions are to STATE_DIALING state for a successful call or STATE_DISCONNECTED if it failed.

Constant Value: 9 (0x00000009)

STATE_DIALING

added in API level 23
int STATE_DIALING

The state of an outgoing Call when dialing the remote number, but not yet connected.

Constant Value: 1 (0x00000001)

STATE_DISCONNECTED

added in API level 23
int STATE_DISCONNECTED

The state of a Call when no further voice or other communication is being transmitted, the remote side has been or will inevitably be informed that the Call is no longer active, and the local data transport has or inevitably will release resources associated with this Call.

Constant Value: 7 (0x00000007)

STATE_DISCONNECTING

added in API level 23
int STATE_DISCONNECTING

The state of a Call when the user has initiated a disconnection of the call, but the call has not yet been disconnected by the underlying ConnectionService. The next state of the call is (potentially) STATE_DISCONNECTED.

Constant Value: 10 (0x0000000a)

STATE_HOLDING

added in API level 23
int STATE_HOLDING

The state of a Call when in a holding state.

Constant Value: 3 (0x00000003)

STATE_NEW

added in API level 23
int STATE_NEW

The state of a Call when newly created.

Constant Value: 0 (0x00000000)

STATE_PULLING_CALL

added in API level 25
int STATE_PULLING_CALL

The state of an external call which is in the process of being pulled from a remote device to the local device.

A call can only be in this state if the PROPERTY_IS_EXTERNAL_CALL property and CAPABILITY_CAN_PULL_CALL capability are set on the call.

An InCallService will only see this state if it has the METADATA_INCLUDE_EXTERNAL_CALLS metadata set to true in its manifest.

Constant Value: 11 (0x0000000b)

STATE_RINGING

added in API level 23
int STATE_RINGING

The state of an incoming Call when ringing locally, but not yet connected.

Constant Value: 2 (0x00000002)

STATE_SELECT_PHONE_ACCOUNT

added in API level 23
int STATE_SELECT_PHONE_ACCOUNT

The state of an outgoing Call when waiting on user to select a PhoneAccount through which to place the call.

Constant Value: 8 (0x00000008)

Public methods

answer

added in API level 23
void answer (int videoState)

Instructs this STATE_RINGING Call to answer.

Parameters
videoState int: The video state in which to answer the call.

Value is either 0 or combination of STATE_AUDIO_ONLY, STATE_TX_ENABLED, STATE_RX_ENABLED, STATE_BIDIRECTIONAL or STATE_PAUSED.

conference

added in API level 23
void conference (Call callToConferenceWith)

Instructs this Call to enter a conference.

Parameters
callToConferenceWith Call: The other call with which to conference.

deflect

void deflect (Uri address)

Instructs this STATE_RINGING Call to deflect.

Parameters
address Uri: The address to which the call will be deflected.

disconnect

added in API level 23
void disconnect ()

Instructs this Call to disconnect.

getCannedTextResponses

added in API level 23
List<String> getCannedTextResponses ()

Obtains a list of canned, pre-configured message responses to present to the user as ways of rejecting this Call using via a text message.

Returns
List<String> A list of canned text message responses.

getChildren

added in API level 23
List<Call> getChildren ()

Obtains the children of this conference Call, if any.

Returns
List<Call> The children of this Call if this Call is a conference, or an empty List otherwise.

getConferenceableCalls

added in API level 23
List<Call> getConferenceableCalls ()

Returns the list of Calls with which this Call is allowed to conference.

Returns
List<Call> The list of conferenceable Calls.

getDetails

added in API level 23
Call.Details getDetails ()

Obtains an object containing call details.

Returns
Call.Details A Call.Details object. Depending on the state of the Call, the result may be null.

getParent

added in API level 23
Call getParent ()

Obtains the parent of this Call in a conference, if any.

Returns
Call The parent Call, or null if this Call is not a child of any conference Calls.

getRemainingPostDialSequence

added in API level 23
String getRemainingPostDialSequence ()

Obtains the post-dial sequence remaining to be emitted by this Call, if any.

Returns
String The remaining post-dial sequence, or null if there is no post-dial sequence remaining or this Call is not in a post-dial state.

getRttCall

added in API level 26
Call.RttCall getRttCall ()

Returns this call's RttCall object. The Call.RttCall instance is used to send and receive RTT text data, as well as to change the RTT mode.

Returns
Call.RttCall A Call.RttCall. null if there is no active RTT connection.

getState

added in API level 23
int getState ()

Obtains the state of this Call.

Returns
int A state value, chosen from the STATE_* constants.

getVideoCall

added in API level 23
InCallService.VideoCall getVideoCall ()

Obtains an object that can be used to display video from this Call.

Returns
InCallService.VideoCall An Call.VideoCall.

handoverTo

void handoverTo (PhoneAccountHandle toHandle, 
                int videoState, 
                Bundle extras)

Initiates a handover of this Call to the ConnectionService identified by toHandle. The videoState specified indicates the desired video state after the handover.

A call handover is the process where an ongoing call is transferred from one app (i.e. ConnectionService to another app. The user could, for example, choose to continue a mobile network call in a video calling app. The mobile network call via the Telephony stack is referred to as the source of the handover, and the video calling app is referred to as the destination.

When considering a handover scenario the device this method is called on is considered the initiating device (since the user initiates the handover from this device), and the other device is considered the receiving device.

When this method is called on the initiating device, the Telecom framework will bind to the ConnectionService defined by the toHandle PhoneAccountHandle and invoke onCreateOutgoingHandoverConnection(PhoneAccountHandle, ConnectionRequest) to inform the destination app that a request has been made to handover a call to it. The app returns an instance of Connection to represent the handover call At this point the app should display UI to indicate to the user that a call handover is in process.

The destination app is responsible for communicating the handover request from the initiating device to the receiving device.

When the app on the receiving device receives the handover request, it calls acceptHandover(Uri, int, PhoneAccountHandle) to continue the handover process from the initiating device to the receiving device. At this point the destination app on the receiving device should show UI to allow the user to choose whether they want to continue their call in the destination app.

When the destination app on the receiving device calls acceptHandover(Uri, int, PhoneAccountHandle), Telecom will bind to its ConnectionService and call onCreateIncomingHandoverConnection(PhoneAccountHandle, ConnectionRequest) to inform it of the handover request. The app returns an instance of Connection to represent the handover call.

If the user of the receiving device accepts the handover, the app calls setActive() to complete the handover process; Telecom will disconnect the original call. If the user rejects the handover, the app calls setDisconnected(DisconnectCause) and specifies a DisconnectCause of CANCELED to indicate that the handover has been cancelled.

Telecom will only allow handovers from PhoneAccounts which declare EXTRA_SUPPORTS_HANDOVER_FROM. Similarly, the PhoneAccount specified by toHandle must declare EXTRA_SUPPORTS_HANDOVER_TO.

Errors in the handover process are reported to the InCallService via onHandoverFailed(Call, int). Errors in the handover process are reported to the involved ConnectionServices via onHandoverFailed(ConnectionRequest, int).

Parameters
toHandle PhoneAccountHandle: PhoneAccountHandle of the ConnectionService to handover this call to.

videoState int: Indicates the video state desired after the handover (see the STATE_* constants defined in VideoProfile).

Value is either 0 or combination of STATE_AUDIO_ONLY, STATE_TX_ENABLED, STATE_RX_ENABLED, STATE_BIDIRECTIONAL or STATE_PAUSED.

extras Bundle: Bundle containing extra information to be passed to the ConnectionService

hold

added in API level 23
void hold ()

Instructs this Call to go on hold.

isRttActive

added in API level 26
boolean isRttActive ()

Returns whether this call has an active RTT connection.

Returns
boolean true if there is a connection, false otherwise.

mergeConference

added in API level 23
void mergeConference ()

Merges the calls within this conference. See CAPABILITY_MERGE_CONFERENCE.

phoneAccountSelected

added in API level 23
void phoneAccountSelected (PhoneAccountHandle accountHandle, 
                boolean setDefault)

Notifies this Call that an account has been selected and to proceed with placing an outgoing call. Optionally sets this account as the default account.

Parameters
accountHandle PhoneAccountHandle

setDefault boolean

playDtmfTone

added in API level 23
void playDtmfTone (char digit)

Instructs this Call to play a dual-tone multi-frequency signaling (DTMF) tone. Any other currently playing DTMF tone in the specified call is immediately stopped.

Parameters
digit char: A character representing the DTMF digit for which to play the tone. This value must be one of '0' through '9', '*' or '#'.

postDialContinue

added in API level 23
void postDialContinue (boolean proceed)

Instructs this Call to continue playing a post-dial DTMF string. A post-dial DTMF string is a string of digits entered after a phone number, when dialed, that are immediately sent as DTMF tones to the recipient as soon as the connection is made. If the DTMF string contains a DTMF_CHARACTER_PAUSE symbol, this Call will temporarily pause playing the tones for a pre-defined period of time. If the DTMF string contains a DTMF_CHARACTER_WAIT symbol, this Call will pause playing the tones and notify callbacks via onPostDialWait(Call, String). At this point, the in-call app should display to the user an indication of this state and an affordance to continue the postdial sequence. When the user decides to continue the postdial sequence, the in-call app should invoke the postDialContinue(boolean) method.

Parameters
proceed boolean: Whether or not to continue with the post-dial sequence.

pullExternalCall

added in API level 25
void pullExternalCall ()

Initiates a request to the ConnectionService to pull an external call to the local device.

Calls to this method are ignored if the call does not have the PROPERTY_IS_EXTERNAL_CALL property set.

An InCallService will only see calls which support this method if it has the METADATA_INCLUDE_EXTERNAL_CALLS metadata set to true in its manifest.

putExtras

added in API level 25
void putExtras (Bundle extras)

Adds some extras to this Call. Existing keys are replaced and new ones are added.

No assumptions should be made as to how an In-Call UI or service will handle these extras. Keys should be fully qualified (e.g., com.example.MY_EXTRA) to avoid conflicts.

Parameters
extras Bundle: The extras to add.

registerCallback

added in API level 23
void registerCallback (Call.Callback callback)

Registers a callback to this Call.

Parameters
callback Call.Callback: A Callback.

registerCallback

added in API level 23
void registerCallback (Call.Callback callback, 
                Handler handler)

Registers a callback to this Call.

Parameters
callback Call.Callback: A Callback.

handler Handler: A handler which command and status changes will be delivered to.

reject

added in API level 23
void reject (boolean rejectWithMessage, 
                String textMessage)

Instructs this STATE_RINGING Call to reject.

Parameters
rejectWithMessage boolean: Whether to reject with a text message.

textMessage String: An optional text message with which to respond.

removeExtras

added in API level 25
void removeExtras (List<String> keys)

Removes extras from this Call.

Parameters
keys List: The keys of the extras to remove.

removeExtras

added in API level 25
void removeExtras (String... keys)

Removes extras from this Call.

Parameters
keys String: The keys of the extras to remove.

respondToRttRequest

added in API level 26
void respondToRttRequest (int id, 
                boolean accept)

Responds to an RTT request received via the onRttRequest(Call, int) )} callback. The ID used here should be the same as the ID that was received via the callback.

Parameters
id int: The request ID received via onRttRequest(Call, int)

accept boolean: true if the RTT request should be accepted, false otherwise.

sendCallEvent

added in API level 25
void sendCallEvent (String event, 
                Bundle extras)

Sends a Call event from this Call to the associated Connection in the ConnectionService.

Call events are used to communicate point in time information from an InCallService to a ConnectionService. A ConnectionService implementation could define events which enable the InCallService, for example, toggle a unique feature of the ConnectionService.

A ConnectionService can communicate to the InCallService using sendConnectionEvent(String, Bundle).

Events are exposed to ConnectionService implementations via onCallEvent(String, Bundle).

No assumptions should be made as to how a ConnectionService will handle these events. The InCallService must assume that the ConnectionService could chose to ignore some events altogether.

Events should be fully qualified (e.g., com.example.event.MY_EVENT) to avoid conflicts between InCallService implementations. Further, InCallService implementations shall not re-purpose events in the android.* namespace, nor shall they define their own event types in this namespace. When defining a custom event type, ensure the contents of the extras Bundle is clearly defined. Extra keys for this bundle should be named similar to the event type (e.g. com.example.extra.MY_EXTRA).

When defining events and the associated extras, it is important to keep their behavior consistent when the associated InCallService is updated. Support for deprecated events/extras should me maintained to ensure backwards compatibility with older ConnectionService implementations which were built to support the older behavior.

Parameters
event String: The connection event.

extras Bundle: Bundle containing extra information associated with the event.

sendRttRequest

added in API level 26
void sendRttRequest ()

Sends an RTT upgrade request to the remote end of the connection. Success is not guaranteed, and notification of success will be via the onRttStatusChanged(Call, boolean, RttCall) callback.

splitFromConference

added in API level 23
void splitFromConference ()

Instructs this Call to split from any conference call with which it may be connected.

stopDtmfTone

added in API level 23
void stopDtmfTone ()

Instructs this Call to stop any dual-tone multi-frequency signaling (DTMF) tone currently playing. DTMF tones are played by calling playDtmfTone(char). If no DTMF tone is currently playing, this method will do nothing.

stopRtt

added in API level 26
void stopRtt ()

Terminate the RTT session on this call. The resulting state change will be notified via the onRttStatusChanged(Call, boolean, RttCall) callback.

swapConference

added in API level 23
void swapConference ()

Swaps the calls within this conference. See CAPABILITY_SWAP_CONFERENCE.

toString

added in API level 23
String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.

unhold

added in API level 23
void unhold ()

Instructs this STATE_HOLDING call to release from hold.

unregisterCallback

added in API level 23
void unregisterCallback (Call.Callback callback)

Unregisters a callback from this Call.

Parameters
callback Call.Callback: A Callback.