Call

AVAILABLE_PHONE_ACCOUNTS

static val AVAILABLE_PHONE_ACCOUNTS: String

Deprecated: Use the list from EXTRA_SUGGESTED_PHONE_ACCOUNTS instead.

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.

Value: "selectPhoneAccountAccounts"

EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS

static val EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS: String

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.

Value: "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS"

EXTRA_SILENT_RINGING_REQUESTED

static val EXTRA_SILENT_RINGING_REQUESTED: String

Extra key used to indicate whether a CallScreeningService has requested to silence the ringtone for a call. If the InCallService declares TelecomManager#METADATA_IN_CALL_SERVICE_RINGING in its manifest, it should not play a ringtone for an incoming call with this extra key set.

Value: "android.telecom.extra.SILENT_RINGING_REQUESTED"

EXTRA_SUGGESTED_PHONE_ACCOUNTS

static val EXTRA_SUGGESTED_PHONE_ACCOUNTS: String

Key for extra used to pass along a list of PhoneAccountSuggestions to the in-call UI when a call enters the STATE_SELECT_PHONE_ACCOUNT state. The list included here will have the same length and be in the same order as the list passed with AVAILABLE_PHONE_ACCOUNTS.

Value: "android.telecom.extra.SUGGESTED_PHONE_ACCOUNTS"

STATE_ACTIVE

static val STATE_ACTIVE: Int

The state of a Call when actively supporting conversation.

Value: 4

STATE_CONNECTING

static val STATE_CONNECTING: Int

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

Value: 9

STATE_DIALING

static val STATE_DIALING: Int

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

Value: 1

STATE_DISCONNECTED

static val STATE_DISCONNECTED: Int

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.

Value: 7

STATE_DISCONNECTING

static val STATE_DISCONNECTING: Int

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.

Value: 10

STATE_HOLDING

static val STATE_HOLDING: Int

The state of a Call when in a holding state.

Value: 3

STATE_NEW

static val STATE_NEW: Int

The state of a Call when newly created.

Value: 0

STATE_PULLING_CALL

static val STATE_PULLING_CALL: Int

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 Details#PROPERTY_IS_EXTERNAL_CALL property and Details#CAPABILITY_CAN_PULL_CALL capability are set on the call.

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

Value: 11

STATE_RINGING

static val STATE_RINGING: Int

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

Value: 2

STATE_SELECT_PHONE_ACCOUNT

static val STATE_SELECT_PHONE_ACCOUNT: Int

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

Value: 8

answer

fun answer(videoState: Int): Unit

Instructs this STATE_RINGING Call to answer.

conference

fun conference(callToConferenceWith: Call!): Unit

Instructs this Call to enter a conference.

deflect

fun deflect(address: Uri!): Unit

Instructs this STATE_RINGING Call to deflect.

disconnect

fun disconnect(): Unit

Instructs this Call to disconnect.

getCannedTextResponses

fun getCannedTextResponses(): MutableList<String!>!

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.

getChildren

fun getChildren(): MutableList<Call!>!

Obtains the children of this conference Call, if any.

getConferenceableCalls

fun getConferenceableCalls(): MutableList<Call!>!

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

getDetails

fun getDetails(): Call.Details!

Obtains an object containing call details.

getParent

fun getParent(): Call!

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

getRemainingPostDialSequence

fun getRemainingPostDialSequence(): String!

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

getRttCall

fun getRttCall(): Call.RttCall?

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

getState

fun getState(): Int

Obtains the state of this Call.

getVideoCall

fun getVideoCall(): InCallService.VideoCall!

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

handoverTo

fun handoverTo(
    toHandle: PhoneAccountHandle!, 
    videoState: Int, 
    extras: Bundle!
): Unit

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 ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle, 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 TelecomManager#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 TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle), Telecom will bind to its ConnectionService and call ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle, 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 Connection#setActive() to complete the handover process; Telecom will disconnect the original call. If the user rejects the handover, the app calls Connection#setDisconnected(DisconnectCause) and specifies a DisconnectCause of DisconnectCause#CANCELED to indicate that the handover has been cancelled.

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

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

hold

fun hold(): Unit

Instructs this Call to go on hold.

isRttActive

fun isRttActive(): Boolean

Returns whether this call has an active RTT connection.

mergeConference

fun mergeConference(): Unit

Merges the calls within this conference. See Details#CAPABILITY_MERGE_CONFERENCE.

phoneAccountSelected

fun phoneAccountSelected(
    accountHandle: PhoneAccountHandle!, 
    setDefault: Boolean
): Unit

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.

playDtmfTone

fun playDtmfTone(digit: Char): Unit

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.

postDialContinue

fun postDialContinue(proceed: Boolean): Unit

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 TelecomManager#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 TelecomManager#DTMF_CHARACTER_WAIT symbol, this Call will pause playing the tones and notify callbacks via Callback#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.

pullExternalCall

fun pullExternalCall(): Unit

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 Call.Details#PROPERTY_IS_EXTERNAL_CALL property set.

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

putExtras

fun putExtras(extras: Bundle!): Unit

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.

registerCallback

fun registerCallback(callback: Call.Callback!): Unit

Registers a callback to this Call.

registerCallback

fun registerCallback(
    callback: Call.Callback!, 
    handler: Handler!
): Unit

Registers a callback to this Call.

reject

fun reject(
    rejectWithMessage: Boolean, 
    textMessage: String!
): Unit

Instructs this STATE_RINGING Call to reject.

removeExtras

fun removeExtras(keys: MutableList<String!>!): Unit

Removes extras from this Call.

removeExtras

fun removeExtras(vararg keys: String!): Unit

Removes extras from this Call.

respondToRttRequest

fun respondToRttRequest(
    id: Int, 
    accept: Boolean
): Unit

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

sendCallEvent

fun sendCallEvent(
    event: String!, 
    extras: Bundle!
): Unit

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 Connection#sendConnectionEvent(String, Bundle).

Events are exposed to ConnectionService implementations via android.telecom.Connection#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.

sendRttRequest

fun sendRttRequest(): Unit

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

splitFromConference

fun splitFromConference(): Unit

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

stopDtmfTone

fun stopDtmfTone(): Unit

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

fun stopRtt(): Unit

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

swapConference

fun swapConference(): Unit

Swaps the calls within this conference. See Details#CAPABILITY_SWAP_CONFERENCE.

toString

fun toString(): String

unhold

fun unhold(): Unit

Instructs this STATE_HOLDING call to release from hold.

unregisterCallback

fun unregisterCallback(callback: Call.Callback!): Unit

Unregisters a callback from this Call.