added in API level 23

Connection

public abstract class Connection
extends Conferenceable

java.lang.Object
↳	android.telecom.Conferenceable
	↳	android.telecom.Connection

Represents a phone call or connection to a remote endpoint that carries voice and/or video traffic.

Implementations create a custom subclass of Connection and return it to the framework as the return value of onCreateIncomingConnection(PhoneAccountHandle, ConnectionRequest) or onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest). Implementations are then responsible for updating the state of the Connection, and must call destroy() to signal to the framework that the Connection is no longer used and associated resources may be recovered.

Subclasses of Connection override the on* methods to provide the the ConnectionService's implementation of calling functionality. The on* methods are called by Telecom to inform an instance of a Connection of actions specific to that Connection instance.

Basic call support requires overriding the following methods: onAnswer(), onDisconnect(), onReject(), onAbort()

Where a Connection has CAPABILITY_SUPPORT_HOLD, the onHold() and onUnhold() methods should be overridden to provide hold support for the Connection.

Where a Connection supports a variation of video calling (e.g. the CAPABILITY_SUPPORTS_VT_* capability bits), onAnswer(int) should be overridden to support answering a call as a video call.

Where a Connection has PROPERTY_IS_EXTERNAL_CALL and CAPABILITY_CAN_PULL_CALL, onPullExternalCall() should be overridden to provide support for pulling the external call.

Where a Connection supports conference calling onSeparate() should be overridden.

There are a number of other on* methods which a Connection can choose to implement, depending on whether it is concerned with the associated calls from Telecom. If, for example, call events from a InCallService are handled, onCallEvent(String, Bundle) should be overridden. Another example is onExtrasChanged(Bundle), which should be overridden if the Connection wishes to make use of extra information provided via the putExtras(Bundle) and removeExtras(String) methods.

Summary

Nested classes
`class`	`Connection.RttModifyStatus` Provides constants to represent the results of responses to session modify requests sent via `sendRttRequest()`
`class`	`Connection.VideoProvider` Provides a means of controlling the video session associated with a `Connection`.

Constants
`int`	`CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO` When set, prevents a video call from being downgraded to an audio-only call.
`int`	`CAPABILITY_CAN_PAUSE_VIDEO` For video calls, indicates whether the outgoing video for the call can be paused using the `STATE_PAUSED` VideoState.
`int`	`CAPABILITY_CAN_PULL_CALL` When set for an external connection, indicates that this `Connection` can be pulled from a remote device to the current device.
`int`	`CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION` Indicates that the connection itself wants to handle any sort of reply response, rather than relying on SMS.
`int`	`CAPABILITY_CAN_UPGRADE_TO_VIDEO` Call can be upgraded to a video call.
`int`	`CAPABILITY_DISCONNECT_FROM_CONFERENCE` Connection is able to be individually disconnected when in a `Conference`.
`int`	`CAPABILITY_HOLD` Connection can currently be put on hold or unheld.
`int`	`CAPABILITY_MANAGE_CONFERENCE` Connection supports conference management.
`int`	`CAPABILITY_MERGE_CONFERENCE` Connections within a conference can be merged.
`int`	`CAPABILITY_MUTE` Connection can be muted.
`int`	`CAPABILITY_RESPOND_VIA_TEXT` Connection supports responding via text option.
`int`	`CAPABILITY_SEPARATE_FROM_CONFERENCE` Connection is able to be separated from its parent `Conference`, if any.
`int`	`CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL` Local device supports bidirectional video calling.
`int`	`CAPABILITY_SUPPORTS_VT_LOCAL_RX` Local device supports receiving video.
`int`	`CAPABILITY_SUPPORTS_VT_LOCAL_TX` Local device supports transmitting video.
`int`	`CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL` Remote device supports bidirectional video calling.
`int`	`CAPABILITY_SUPPORTS_VT_REMOTE_RX` Remote device supports receiving video.
`int`	`CAPABILITY_SUPPORTS_VT_REMOTE_TX` Remote device supports transmitting video.
`int`	`CAPABILITY_SUPPORT_HOLD` Connection supports the hold feature.
`int`	`CAPABILITY_SWAP_CONFERENCE` Connections within a conference can be swapped between foreground and background.
`String`	`EVENT_CALL_MERGE_FAILED` Connection event used to inform `InCallService`s when the merging of two calls has failed.
`String`	`EVENT_CALL_PULL_FAILED` Connection event used to inform `InCallService`s when pulling of an external call has failed.
`String`	`EXTRA_ANSWERING_DROPS_FG_CALL` Boolean connection extra key set on a `Connection` in `STATE_RINGING` state to indicate that answering the call will cause the current active foreground call to be dropped.
`String`	`EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME` String connection extra key set on a `Connection` in `STATE_RINGING` state to indicate the name of the third-party app which is responsible for the current foreground call.
`String`	`EXTRA_CALL_SUBJECT` Connection extra key used to store the subject for an incoming call.
`String`	`EXTRA_CHILD_ADDRESS` Connection extra key used to store a child number associated with the current connection.
`String`	`EXTRA_LAST_FORWARDED_NUMBER` Connection extra key used to store the last forwarded number associated with the current connection.
`int`	`PROPERTY_HAS_CDMA_VOICE_PRIVACY` Indicates that the connection has CDMA Enhanced Voice Privacy enabled.
`int`	`PROPERTY_IS_EXTERNAL_CALL` When set, indicates that the `Connection` does not actually exist locally for the `ConnectionService`.
`int`	`PROPERTY_SELF_MANAGED` Set by the framework to indicate that the `Connection` originated from a self-managed `ConnectionService`.
`int`	`STATE_ACTIVE` A connection is active.
`int`	`STATE_DIALING` An outgoing connection is in the dialing state.
`int`	`STATE_DISCONNECTED` A connection has been disconnected.
`int`	`STATE_HOLDING` A connection is on hold.
`int`	`STATE_INITIALIZING` The connection is initializing.
`int`	`STATE_NEW` The connection is new and not connected.
`int`	`STATE_PULLING_CALL` The state of an external connection which is in the process of being pulled from a remote device to the local device.
`int`	`STATE_RINGING` An incoming connection is in the ringing state.

Public constructors
`Connection()` Create a new Connection.

Public methods
`static String`	`capabilitiesToString(int capabilities)` Renders a set of capability bits (`CAPABILITY_*`) as a human readable string.
`static Connection`	`createCanceledConnection()` Return a `Connection` which represents a canceled connection attempt.
`static Connection`	`createFailedConnection(DisconnectCause disconnectCause)` Return a `Connection` which represents a failed connection attempt.
`final void`	`destroy()` Tears down the Connection object.
`final Uri`	`getAddress()`
`final int`	`getAddressPresentation()`
`final boolean`	`getAudioModeIsVoip()`
`final CallAudioState`	`getCallAudioState()`
`final String`	`getCallerDisplayName()`
`final int`	`getCallerDisplayNamePresentation()`
`final Conference`	`getConference()`
`final List<Conferenceable>`	`getConferenceables()` Returns the connections or conferences with which this connection can be conferenced.
`final int`	`getConnectionCapabilities()` Returns the connection's capabilities, as a bit mask of the `CAPABILITY_*` constants.
`final int`	`getConnectionProperties()` Returns the connection's properties, as a bit mask of the `PROPERTY_*` constants.
`final DisconnectCause`	`getDisconnectCause()`
`final Bundle`	`getExtras()` Returns the extras associated with this connection.
`final int`	`getState()`
`final StatusHints`	`getStatusHints()`
`final Connection.VideoProvider`	`getVideoProvider()`
`final boolean`	`isRingbackRequested()` Returns whether this connection is requesting that the system play a ringback tone on its behalf.
`void`	`onAbort()` Notifies this Connection of a request to abort.
`void`	`onAnswer(int videoState)` Notifies this Connection, which is in `STATE_RINGING`, of a request to accept.
`void`	`onAnswer()` Notifies this Connection, which is in `STATE_RINGING`, of a request to accept.
`void`	`onCallAudioStateChanged(CallAudioState state)` Notifies this Connection that the `getCallAudioState()` property has a new value.
`void`	`onCallEvent(String event, Bundle extras)` Notifies this Connection of a `Call` event initiated from an `InCallService`.
`void`	`onDisconnect()` Notifies this Connection of a request to disconnect.
`void`	`onExtrasChanged(Bundle extras)` Notifies this `Connection` of a change to the extras made outside the `ConnectionService`.
`void`	`onHold()` Notifies this Connection of a request to hold.
`void`	`onPlayDtmfTone(char c)` Notifies this Connection of a request to play a DTMF tone.
`void`	`onPostDialContinue(boolean proceed)` Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.
`void`	`onPullExternalCall()` Notifies this Connection of a request to pull an external call to the local device.
`void`	`onReject()` Notifies this Connection, which is in `STATE_RINGING`, of a request to reject.
`void`	`onReject(String replyMessage)` Notifies this Connection, which is in `STATE_RINGING`, of a request to reject with a message.
`void`	`onSeparate()` Notifies this Connection of a request to separate from its parent conference.
`void`	`onShowIncomingCallUi()` Notifies this `Connection` that its `ConnectionService` is responsible for displaying its incoming call user interface for the `Connection`.
`void`	`onStateChanged(int state)` Notifies this Connection of an internal state change.
`void`	`onStopDtmfTone()` Notifies this Connection of a request to stop any currently playing DTMF tones.
`void`	`onUnhold()` Notifies this Connection of a request to exit a hold state.
`static String`	`propertiesToString(int properties)` Renders a set of property bits (`PROPERTY_*`) as a human readable string.
`final void`	`putExtras(Bundle extras)` Adds some extras to this `Connection`.
`final void`	`removeExtras(String... keys)` Removes extras from this `Connection`.
`final void`	`removeExtras(List<String> keys)` Removes extras from this `Connection`.
`void`	`sendConnectionEvent(String event, Bundle extras)` Sends an event associated with this `Connection` with associated event extras to the `InCallService`.
`final void`	`setActive()` Sets state to active (e.g., an ongoing connection where two or more parties can actively communicate).
`final void`	`setAddress(Uri address, int presentation)` Sets the value of the `getAddress()` property.
`final void`	`setAudioModeIsVoip(boolean isVoip)` Requests that the framework use VOIP audio mode for this connection.
`final void`	`setAudioRoute(int route)` Sets the audio route (speaker, bluetooth, etc...).
`final void`	`setCallerDisplayName(String callerDisplayName, int presentation)` Sets the caller display name (CNAP).
`final void`	`setConferenceableConnections(List<Connection> conferenceableConnections)` Sets the connections with which this connection can be conferenced.
`final void`	`setConferenceables(List<Conferenceable> conferenceables)` Similar to `setConferenceableConnections(java.util.List)`, sets a list of connections or conferences with which this connection can be conferenced.
`final void`	`setConnectionCapabilities(int connectionCapabilities)` Sets the connection's capabilities as a bit mask of the `CAPABILITY_*` constants.
`final void`	`setConnectionProperties(int connectionProperties)` Sets the connection's properties as a bit mask of the `PROPERTY_*` constants.
`final void`	`setDialing()` Sets state to dialing (e.g., dialing an outbound connection).
`final void`	`setDisconnected(DisconnectCause disconnectCause)` Sets state to disconnected.
`final void`	`setExtras(Bundle extras)` Set some extras that can be associated with this `Connection`.
`final void`	`setInitialized()` Sets state to initialized (the Connection has been set up and is now ready to be used).
`final void`	`setInitializing()` Sets state to initializing (this Connection is not yet ready to be used).
`final void`	`setNextPostDialChar(char nextChar)` Informs listeners that this `Connection` has processed a character in the post-dial started state.
`final void`	`setOnHold()` Sets state to be on hold.
`final void`	`setPostDialWait(String remaining)` Informs listeners that this `Connection` is in a post-dial wait state.
`final void`	`setPulling()` Sets state to pulling (e.g.
`final void`	`setRingbackRequested(boolean ringback)` Requests that the framework play a ringback tone.
`final void`	`setRinging()` Sets state to ringing (e.g., an inbound ringing connection).
`final void`	`setStatusHints(StatusHints statusHints)` Sets the label and icon status to display in the in-call UI.
`final void`	`setVideoProvider(Connection.VideoProvider videoProvider)` Sets the video connection provider.
`final void`	`setVideoState(int videoState)` Set the video state for the connection.
`static String`	`stateToString(int state)`

Inherited methods

From class


  
    java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long millis, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void`	`wait(long millis)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void`	`wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

Constants

CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO

added in API level 24

int CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO

When set, prevents a video call from being downgraded to an audio-only call.

Should be set when the VideoState has the STATE_TX_ENABLED or STATE_RX_ENABLED bits set to indicate that the connection cannot be downgraded from a video call back to a VideoState of STATE_AUDIO_ONLY.

Intuitively, a call which can be downgraded to audio should also have local and remote video capabilities (see CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL and CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL).

Constant Value: 8388608 (0x00800000)

CAPABILITY_CAN_PAUSE_VIDEO

added in API level 23

int CAPABILITY_CAN_PAUSE_VIDEO

For video calls, indicates whether the outgoing video for the call can be paused using the STATE_PAUSED VideoState.

Constant Value: 1048576 (0x00100000)

CAPABILITY_CAN_PULL_CALL

added in API level 25

int CAPABILITY_CAN_PULL_CALL

When set for an external connection, indicates that this Connection can be pulled from a remote device to the current device.

Should only be set on a Connection where PROPERTY_IS_EXTERNAL_CALL is set.

Constant Value: 16777216 (0x01000000)

CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION

added in API level 24

int CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION

Indicates that the connection itself wants to handle any sort of reply response, rather than relying on SMS.

Constant Value: 4194304 (0x00400000)

CAPABILITY_CAN_UPGRADE_TO_VIDEO

added in API level 23

int CAPABILITY_CAN_UPGRADE_TO_VIDEO

Call can be upgraded to a video call.

Constant Value: 524288 (0x00080000)

CAPABILITY_DISCONNECT_FROM_CONFERENCE

added in API level 23

int CAPABILITY_DISCONNECT_FROM_CONFERENCE

Connection is able to be individually disconnected when in a Conference.

Constant Value: 8192 (0x00002000)

CAPABILITY_HOLD

added in API level 23

int CAPABILITY_HOLD

Connection can currently be put on hold or unheld. This is distinct from CAPABILITY_SUPPORT_HOLD in that although a connection may support 'hold' most times, it does not at the moment support the function. This can be true while the call is in the state STATE_DIALING, for example. During this condition, an in-call UI may display a disabled 'hold' button.

Constant Value: 1 (0x00000001)

CAPABILITY_MANAGE_CONFERENCE

added in API level 23

int CAPABILITY_MANAGE_CONFERENCE

Connection supports conference management. This capability only applies to Conferences which can have Connections as children.

Constant Value: 128 (0x00000080)

CAPABILITY_MERGE_CONFERENCE

added in API level 23

int CAPABILITY_MERGE_CONFERENCE

Connections within a conference can be merged. A ConnectionService has the option to add a Conference before the child Connections are merged. This is how CDMA-based Connections are implemented. For these unmerged Conferences, this capability allows a merge button to be shown while the conference is in the foreground of the in-call UI.

This is only intended for use by a Conference.

Constant Value: 4 (0x00000004)

CAPABILITY_MUTE

added in API level 23

int CAPABILITY_MUTE

Connection can be muted.

Constant Value: 64 (0x00000040)

CAPABILITY_RESPOND_VIA_TEXT

added in API level 23

int CAPABILITY_RESPOND_VIA_TEXT

Connection supports responding via text option.

Constant Value: 32 (0x00000020)

CAPABILITY_SEPARATE_FROM_CONFERENCE

added in API level 23

int CAPABILITY_SEPARATE_FROM_CONFERENCE

Connection is able to be separated from its parent Conference, if any.

Constant Value: 4096 (0x00001000)

CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL

added in API level 23

int CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL

Local device supports bidirectional video calling.

Constant Value: 768 (0x00000300)

CAPABILITY_SUPPORTS_VT_LOCAL_RX

added in API level 23

int CAPABILITY_SUPPORTS_VT_LOCAL_RX

Local device supports receiving video.

Constant Value: 256 (0x00000100)

CAPABILITY_SUPPORTS_VT_LOCAL_TX

added in API level 23

int CAPABILITY_SUPPORTS_VT_LOCAL_TX

Local device supports transmitting video.

Constant Value: 512 (0x00000200)

CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL

added in API level 23

int CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL

Remote device supports bidirectional video calling.

Constant Value: 3072 (0x00000c00)

CAPABILITY_SUPPORTS_VT_REMOTE_RX

added in API level 23

int CAPABILITY_SUPPORTS_VT_REMOTE_RX

Remote device supports receiving video.

Constant Value: 1024 (0x00000400)

CAPABILITY_SUPPORTS_VT_REMOTE_TX

added in API level 23

int CAPABILITY_SUPPORTS_VT_REMOTE_TX

Remote device supports transmitting video.

Constant Value: 2048 (0x00000800)

CAPABILITY_SUPPORT_HOLD

added in API level 23

int CAPABILITY_SUPPORT_HOLD

Connection supports the hold feature.

Constant Value: 2 (0x00000002)

CAPABILITY_SWAP_CONFERENCE

added in API level 23

int CAPABILITY_SWAP_CONFERENCE

Connections within a conference can be swapped between foreground and background. See CAPABILITY_MERGE_CONFERENCE for additional information.

This is only intended for use by a Conference.

Constant Value: 8 (0x00000008)

EVENT_CALL_MERGE_FAILED

added in API level 25

String EVENT_CALL_MERGE_FAILED

Connection event used to inform InCallServices when the merging of two calls has failed. The User Interface should use this message to inform the user of the error.

Sent via sendConnectionEvent(String, Bundle). The Bundle parameter is expected to be null when this connection event is used.

Constant Value: "android.telecom.event.CALL_MERGE_FAILED"

EVENT_CALL_PULL_FAILED

added in API level 25

String EVENT_CALL_PULL_FAILED

Connection event used to inform InCallServices when pulling of an external call has failed. The user interface should inform the user of the error.

Expected to be used by the ConnectionService when the pullExternalCall() API is called on a Call with the properties PROPERTY_IS_EXTERNAL_CALL and CAPABILITY_CAN_PULL_CALL, but the ConnectionService could not pull the external call due to an error condition.

Sent via sendConnectionEvent(String, Bundle). The Bundle parameter is expected to be null when this connection event is used.

Constant Value: "android.telecom.event.CALL_PULL_FAILED"

EXTRA_ANSWERING_DROPS_FG_CALL

added in API level 25

String EXTRA_ANSWERING_DROPS_FG_CALL

Boolean connection extra key set on a Connection in STATE_RINGING state to indicate that answering the call will cause the current active foreground call to be dropped.

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

EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME

Android O Developer Preview

String EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME

String connection extra key set on a Connection in STATE_RINGING state to indicate the name of the third-party app which is responsible for the current foreground call.

Used when EXTRA_ANSWERING_DROPS_FG_CALL is true to ensure that the default Phone app is able to inform the user that answering the new incoming call will cause a call owned by another app to be dropped when the incoming call is answered.

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

EXTRA_CALL_SUBJECT

added in API level 23

String EXTRA_CALL_SUBJECT

Connection extra key used to store the subject for an incoming call. The user interface can query this extra and display its contents for incoming calls. Will only be used if the PhoneAccount supports the capability CAPABILITY_CALL_SUBJECT.

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

EXTRA_CHILD_ADDRESS

added in API level 23

String EXTRA_CHILD_ADDRESS

Connection extra key used to store a child number associated with the current connection. Used to communicate to the user interface that the connection was received via a child address (i.e. phone number) associated with the PhoneAccount's primary address.

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

EXTRA_LAST_FORWARDED_NUMBER

added in API level 23

String EXTRA_LAST_FORWARDED_NUMBER

Connection extra key used to store the last forwarded number associated with the current connection. Used to communicate to the user interface that the connection was forwarded via the specified number.

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

PROPERTY_HAS_CDMA_VOICE_PRIVACY

added in API level 25

int PROPERTY_HAS_CDMA_VOICE_PRIVACY

Indicates that the connection has CDMA Enhanced Voice Privacy enabled.

Constant Value: 32 (0x00000020)

PROPERTY_IS_EXTERNAL_CALL

added in API level 25

int PROPERTY_IS_EXTERNAL_CALL

When set, indicates that the Connection does not actually exist locally for the ConnectionService.

Consider, for example, a scenario where a user has two devices with the same phone number. When a user places a call on one devices, the telephony stack can represent that call on the other device by adding is to the ConnectionService with the PROPERTY_IS_EXTERNAL_CALL capability set.

An ConnectionService should not assume that all InCallServices will handle external connections. Only those InCallServices which have the METADATA_INCLUDE_EXTERNAL_CALLS metadata set to true in its manifest will see external connections.

Constant Value: 16 (0x00000010)

PROPERTY_SELF_MANAGED

Android O Developer Preview

int PROPERTY_SELF_MANAGED

Set by the framework to indicate that the Connection originated from a self-managed ConnectionService.

See CAPABILITY_SELF_MANAGED.

Constant Value: 128 (0x00000080)

STATE_ACTIVE

added in API level 23

int STATE_ACTIVE

A connection is active. Both parties are connected to the call and can actively communicate.

Constant Value: 4 (0x00000004)

STATE_DIALING

added in API level 23

int STATE_DIALING

An outgoing connection is in the dialing state. In this state the other party has not yet answered the call and the user traditionally hears a ringback tone.

Constant Value: 3 (0x00000003)

STATE_DISCONNECTED

added in API level 23

int STATE_DISCONNECTED

A connection has been disconnected. This is the final state once the user has been disconnected from a call either locally, remotely or by an error in the service.

Constant Value: 6 (0x00000006)

STATE_HOLDING

added in API level 23

int STATE_HOLDING

A connection is on hold.

Constant Value: 5 (0x00000005)

STATE_INITIALIZING

added in API level 23

int STATE_INITIALIZING

The connection is initializing. This is generally the first state for a Connection returned by a ConnectionService.

Constant Value: 0 (0x00000000)

STATE_NEW

added in API level 23

int STATE_NEW

The connection is new and not connected.

Constant Value: 1 (0x00000001)

STATE_PULLING_CALL

added in API level 25

int STATE_PULLING_CALL

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

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

Constant Value: 7 (0x00000007)

STATE_RINGING

added in API level 23

int STATE_RINGING

An incoming connection is in the ringing state. During this state, the user's ringer or vibration feature will be activated.

Constant Value: 2 (0x00000002)

Public constructors

Connection

added in API level 23

Connection ()

Create a new Connection.

Public methods

capabilitiesToString

added in API level 23

String capabilitiesToString (int capabilities)

Renders a set of capability bits (CAPABILITY_*) as a human readable string.

Parameters
`capabilities`	`int`: A capability bit field.

Returns
`String`	A human readable string representation.

createCanceledConnection

added in API level 23

Connection createCanceledConnection ()

Return a Connection which represents a canceled connection attempt. The returned Connection will have state STATE_DISCONNECTED, and cannot be moved out of that state. This connection should not be used for anything, and no other Connections should be attempted.

so users of this method need not maintain a reference to its return value to destroy it.

Returns
`Connection`	A `Connection` which indicates that the underlying connection should be canceled.

createFailedConnection

added in API level 23

Connection createFailedConnection (DisconnectCause disconnectCause)

Return a Connection which represents a failed connection attempt. The returned Connection will have a DisconnectCause and as specified, and a getState() of STATE_DISCONNECTED.

The returned Connection can be assumed to destroy() itself when appropriate, so users of this method need not maintain a reference to its return value to destroy it.

Parameters
`disconnectCause`	`DisconnectCause`: The disconnect cause, ().

Returns
`Connection`	A `Connection` which indicates failure.

destroy

added in API level 23

void destroy ()

Tears down the Connection object.

getAddress

added in API level 23

Uri getAddress ()

Returns
`Uri`	The address (e.g., phone number) to which this Connection is currently communicating.

getAddressPresentation

added in API level 23

int getAddressPresentation ()

Returns
`int`	The presentation requirements for the address. See `TelecomManager` for valid values.

getAudioModeIsVoip

added in API level 23

boolean getAudioModeIsVoip ()

Returns
`boolean`	True if the connection's audio mode is VOIP.

getCallAudioState

added in API level 23

CallAudioState getCallAudioState ()

Returns
`CallAudioState`	The audio state of the connection, describing how its audio is currently being routed by the system. This is `null` if this Connection does not directly know about its audio state.

getCallerDisplayName

added in API level 23

String getCallerDisplayName ()

Returns
`String`	The caller display name (CNAP).

getCallerDisplayNamePresentation

added in API level 23

int getCallerDisplayNamePresentation ()

Returns
`int`	The presentation requirements for the handle. See `TelecomManager` for valid values.

getConference

added in API level 23

Conference getConference ()

Returns
`Conference`	The conference that this connection is a part of. Null if it is not part of any conference.

getConferenceables

added in API level 23

List<Conferenceable> getConferenceables ()

Returns the connections or conferences with which this connection can be conferenced.

Returns
`List<Conferenceable>`

getConnectionCapabilities

added in API level 23

int getConnectionCapabilities ()

Returns the connection's capabilities, as a bit mask of the CAPABILITY_* constants.

Returns
`int`

getConnectionProperties

added in API level 25

int getConnectionProperties ()

Returns the connection's properties, as a bit mask of the PROPERTY_* constants.

Returns
`int`

getDisconnectCause

added in API level 23

DisconnectCause getDisconnectCause ()

Returns
`DisconnectCause`	The `DisconnectCause` for this connection.

getExtras

added in API level 23

Bundle getExtras ()

Returns the extras associated with this connection.

Extras should be updated using putExtras(Bundle).

Telecom or an InCallService can also update the extras via putExtras(Bundle), and removeExtras(List).

The connection is notified of changes to the extras made by Telecom or an InCallService by onExtrasChanged(Bundle).

Returns
`Bundle`	The extras associated with this connection.

getState

added in API level 23

int getState ()

Returns
`int`	The state of this Connection.

getStatusHints

added in API level 23

StatusHints getStatusHints ()

Returns
`StatusHints`	The status hints for this connection.

getVideoProvider

added in API level 23

Connection.VideoProvider getVideoProvider ()

Returns
`Connection.VideoProvider`

isRingbackRequested

added in API level 23

boolean isRingbackRequested ()

Returns whether this connection is requesting that the system play a ringback tone on its behalf.

Returns
`boolean`

onAbort

added in API level 23

void onAbort ()

Notifies this Connection of a request to abort.

onAnswer

added in API level 23

void onAnswer (int videoState)

Notifies this Connection, which is in STATE_RINGING, of a request to accept.

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

onAnswer

added in API level 23

void onAnswer ()

Notifies this Connection, which is in STATE_RINGING, of a request to accept.

onCallAudioStateChanged

added in API level 23

void onCallAudioStateChanged (CallAudioState state)

Notifies this Connection that the getCallAudioState() property has a new value.

Parameters
`state`	`CallAudioState`: The new connection audio state.

onCallEvent

added in API level 25

void onCallEvent (String event, 
                Bundle extras)

Notifies this Connection of a Call event initiated from an InCallService.

The InCallService issues a Call event via sendCallEvent(String, Bundle).

Where possible, the Connection should make an attempt to handle Call events which are part of the android.telecom.* namespace. The Connection should ignore any events it does not wish to handle. Unexpected events should be handled gracefully, as it is possible that a InCallService has defined its own Call events which a Connection is not aware of.

Parameters
`event`	`String`: The call event.
`extras`	`Bundle`: Extras associated with the call event.

onDisconnect

added in API level 23

void onDisconnect ()

Notifies this Connection of a request to disconnect.

onExtrasChanged

added in API level 25

void onExtrasChanged (Bundle extras)

Notifies this Connection of a change to the extras made outside the ConnectionService.

These extras changes can originate from Telecom itself, or from an InCallService via the putExtras(Bundle) and removeExtras(List).

Parameters
`extras`	`Bundle`: The new extras bundle.

onHold

added in API level 23

void onHold ()

Notifies this Connection of a request to hold.

onPlayDtmfTone

added in API level 23

void onPlayDtmfTone (char c)

Notifies this Connection of a request to play a DTMF tone.

Parameters
`c`	`char`: A DTMF character.

onPostDialContinue

added in API level 23

void onPostDialContinue (boolean proceed)

Notifies this Connection whether the user wishes to proceed with the post-dial DTMF codes.

Parameters
`proceed`	`boolean`

onPullExternalCall

added in API level 25

void onPullExternalCall ()

Notifies this Connection of a request to pull an external call to the local device.

The InCallService issues a request to pull an external call to the local device via pullExternalCall().

For a Connection to be pulled, both the CAPABILITY_CAN_PULL_CALL capability and PROPERTY_IS_EXTERNAL_CALL property bits must be set.

For more information on external calls, see PROPERTY_IS_EXTERNAL_CALL.

onReject

added in API level 23

void onReject ()

Notifies this Connection, which is in STATE_RINGING, of a request to reject.

onReject

added in API level 24

void onReject (String replyMessage)

Notifies this Connection, which is in STATE_RINGING, of a request to reject with a message.

Parameters
`replyMessage`	`String`

onSeparate

added in API level 23

void onSeparate ()

Notifies this Connection of a request to separate from its parent conference.

onShowIncomingCallUi

Android O Developer Preview

void onShowIncomingCallUi ()

Notifies this Connection that its ConnectionService is responsible for displaying its incoming call user interface for the Connection.

Will only be called for incoming calls added via a self-managed ConnectionService (see CAPABILITY_SELF_MANAGED), where the ConnectionService should show its own incoming call user interface.

Where there are ongoing calls in other self-managed ConnectionServices, or in a regular ConnectionService, the Telecom framework will display its own incoming call user interface to allow the user to choose whether to answer the new incoming call and disconnect other ongoing calls, or to reject the new incoming call.

You should trigger the display of the incoming call user interface for your application by showing a Notification with a full-screen Intent specified. For example:


     // Create an intent which triggers your fullscreen incoming call user interface.
     Intent intent = new Intent(Intent.ACTION_MAIN, null);
     intent.setFlags(Intent.FLAG_ACTIVITY_NO_USER_ACTION | Intent.FLAG_ACTIVITY_NEW_TASK);
     intent.setClass(context, YourIncomingCallActivity.class);
     PendingIntent pendingIntent = PendingIntent.getActivity(context, 1, intent, 0);

     // Build the notification as an ongoing high priority item; this ensures it will show as
     // a heads up notification which slides down over top of the current content.
     final Notification.Builder builder = new Notification.Builder(context);
     builder.setOngoing(true);
     builder.setPriority(Notification.PRIORITY_HIGH);

     // Set notification content intent to take user to fullscreen UI if user taps on the
     // notification body.
     builder.setContentIntent(pendingIntent);
     // Set full screen intent to trigger display of the fullscreen UI when the notification
     // manager deems it appropriate.
     builder.setFullScreenIntent(pendingIntent, true);

     // Setup notification content.
     builder.setSmallIcon( yourIconResourceId );
     builder.setContentTitle("Your notification title");
     builder.setContentText("Your notification content.");

     // Use builder.addAction(..) to add buttons to answer or reject the call.

     NotificationManager notificationManager = mContext.getSystemService(
         NotificationManager.class);
     notificationManager.notify(YOUR_TAG, YOUR_ID, builder.build());

onStateChanged

added in API level 23

void onStateChanged (int state)

Notifies this Connection of an internal state change. This method is called after the state is changed.

Parameters
`state`	`int`: The new state, one of the `STATE_*` constants.

onStopDtmfTone

added in API level 23

void onStopDtmfTone ()

Notifies this Connection of a request to stop any currently playing DTMF tones.

onUnhold

added in API level 23

void onUnhold ()

Notifies this Connection of a request to exit a hold state.

propertiesToString

added in API level 25

String propertiesToString (int properties)

Renders a set of property bits (PROPERTY_*) as a human readable string.

Parameters
`properties`	`int`: A property bit field.

Returns
`String`	A human readable string representation.

putExtras

added in API level 25

void putExtras (Bundle extras)

Adds some extras to this Connection. 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. This value must never be `null`.

removeExtras

added in API level 25

void removeExtras (String... keys)

Removes extras from this Connection.

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

removeExtras

added in API level 25

void removeExtras (List<String> keys)

Removes extras from this Connection.

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

sendConnectionEvent

added in API level 25

void sendConnectionEvent (String event, 
                Bundle extras)

Sends an event associated with this Connection with associated event extras to the InCallService.

Connection events are used to communicate point in time information from a ConnectionService to a InCallService implementations. An example of a custom connection event includes notifying the UI when a WIFI call has been handed over to LTE, which the InCall UI might use to inform the user that billing charges may apply. The Android Telephony framework will send the EVENT_CALL_MERGE_FAILED connection event when a call to mergeConference() has failed to complete successfully. A connection event could also be used to trigger UI in the InCallService which prompts the user to make a choice (e.g. whether they want to incur roaming costs for making a call), which is communicated back via sendCallEvent(String, Bundle).

Events are exposed to InCallService implementations via onConnectionEvent(Call, String, Bundle).

No assumptions should be made as to how an In-Call UI or service will handle these events. The ConnectionService must assume that the In-Call UI could even chose to ignore some events altogether.

Events should be fully qualified (e.g. com.example.event.MY_EVENT) to avoid conflicts between ConnectionService implementations. Further, custom ConnectionService implementations shall not re-purpose events in the android.* namespace, nor shall they define new 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 ConnectionService is updated. Support for deprecated events/extras should me maintained to ensure backwards compatibility with older InCallService implementations which were built to support the older behavior.

Parameters
`event`	`String`: The connection event.
`extras`	`Bundle`: Optional bundle containing extra information associated with the event.

setActive

added in API level 23

void setActive ()

Sets state to active (e.g., an ongoing connection where two or more parties can actively communicate).

setAddress

added in API level 23

void setAddress (Uri address, 
                int presentation)

Sets the value of the getAddress() property.

Parameters
`address`	`Uri`: The new address.
`presentation`	`int`: The presentation requirements for the address. See `TelecomManager` for valid values.

setAudioModeIsVoip

added in API level 23

void setAudioModeIsVoip (boolean isVoip)

Requests that the framework use VOIP audio mode for this connection.

Parameters
`isVoip`	`boolean`: True if the audio mode is VOIP.

setAudioRoute

Android O Developer Preview

void setAudioRoute (int route)

Sets the audio route (speaker, bluetooth, etc...). When this request is honored, there will be change to the getCallAudioState().

Used by self-managed ConnectionServices which wish to change the audio route for a self-managed Connection (see CAPABILITY_SELF_MANAGED.)

Parameters
`route`	`int`: The audio route to use (one of `ROUTE_BLUETOOTH`, `ROUTE_EARPIECE`, `ROUTE_SPEAKER`, or `ROUTE_WIRED_HEADSET`).

setCallerDisplayName

added in API level 23

void setCallerDisplayName (String callerDisplayName, 
                int presentation)

Sets the caller display name (CNAP).

Parameters
`callerDisplayName`	`String`: The new display name.
`presentation`	`int`: The presentation requirements for the handle. See `TelecomManager` for valid values.

setConferenceableConnections

added in API level 23

void setConferenceableConnections (List<Connection> conferenceableConnections)

Sets the connections with which this connection can be conferenced.

Parameters
`conferenceableConnections`	`List`: The set of connections this connection can conference with.

setConferenceables

added in API level 23

void setConferenceables (List<Conferenceable> conferenceables)

Similar to setConferenceableConnections(java.util.List), sets a list of connections or conferences with which this connection can be conferenced.

Parameters
`conferenceables`	`List`: The conferenceables.

setConnectionCapabilities

added in API level 23

void setConnectionCapabilities (int connectionCapabilities)

Sets the connection's capabilities as a bit mask of the CAPABILITY_* constants.

Parameters
`connectionCapabilities`	`int`: The new connection capabilities.

setConnectionProperties

added in API level 25

void setConnectionProperties (int connectionProperties)

Sets the connection's properties as a bit mask of the PROPERTY_* constants.

Parameters
`connectionProperties`	`int`: The new connection properties.

setDialing

added in API level 23

void setDialing ()

Sets state to dialing (e.g., dialing an outbound connection).

setDisconnected

added in API level 23

void setDisconnected (DisconnectCause disconnectCause)

Sets state to disconnected.

Parameters
`disconnectCause`	`DisconnectCause`: The reason for the disconnection, as specified by `DisconnectCause`.

setExtras

added in API level 23

void setExtras (Bundle extras)

Set some extras that can be associated with this Connection.

New or existing keys are replaced in the Connection extras. Keys which are no longer in the new extras, but were present the last time setExtras was called are removed.

Alternatively you may use the putExtras(Bundle), and removeExtras(String) methods to modify the extras.

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 associated with this `Connection`. This value may be `null`.

setInitialized

added in API level 23

void setInitialized ()

Sets state to initialized (the Connection has been set up and is now ready to be used).

setInitializing

added in API level 23

void setInitializing ()

Sets state to initializing (this Connection is not yet ready to be used).

setNextPostDialChar

added in API level 23

void setNextPostDialChar (char nextChar)

Informs listeners that this Connection has processed a character in the post-dial started state. This is done when (a) the Connection is issuing a DTMF sequence; and (b) it wishes to signal Telecom to play the corresponding DTMF tone locally.

Parameters
`nextChar`	`char`: The DTMF character that was just processed by the `Connection`.

setOnHold

added in API level 23

void setOnHold ()

Sets state to be on hold.

setPostDialWait

added in API level 23

void setPostDialWait (String remaining)

Informs listeners that this Connection is in a post-dial wait state. This is done when (a) the Connection is issuing a DTMF sequence; (b) it has encountered a "wait" character; and (c) it wishes to inform the In-Call app that it is waiting for the end-user to send an onPostDialContinue(boolean) signal.

Parameters
`remaining`	`String`: The DTMF character sequence remaining to be emitted once the `onPostDialContinue(boolean)` is received, including any "wait" characters that remaining sequence may contain.

setPulling

added in API level 25

void setPulling ()

Sets state to pulling (e.g. the connection is being pulled to the local device from another device). Only applicable for Connections with PROPERTY_IS_EXTERNAL_CALL and CAPABILITY_CAN_PULL_CALL.

setRingbackRequested

added in API level 23

void setRingbackRequested (boolean ringback)

Requests that the framework play a ringback tone. This is to be invoked by implementations that do not play a ringback tone themselves in the connection's audio stream.

Parameters
`ringback`	`boolean`: Whether the ringback tone is to be played.

setRinging

added in API level 23

void setRinging ()

Sets state to ringing (e.g., an inbound ringing connection).

setStatusHints

added in API level 23

void setStatusHints (StatusHints statusHints)

Sets the label and icon status to display in the in-call UI.

Parameters
`statusHints`	`StatusHints`: The status label and icon to set.

setVideoProvider

added in API level 23

void setVideoProvider (Connection.VideoProvider videoProvider)

Sets the video connection provider.

Parameters
`videoProvider`	`Connection.VideoProvider`: The video provider.

setVideoState

added in API level 23

void setVideoState (int videoState)

Set the video state for the connection. Valid values: STATE_AUDIO_ONLY, STATE_BIDIRECTIONAL, STATE_TX_ENABLED, STATE_RX_ENABLED.

Parameters
`videoState`	`int`: The new video state.

stateToString

added in API level 23

String stateToString (int state)

Parameters
`state`	`int`: An integer value of a `STATE_*` constant.

Returns
`String`	A string representation of the value.

Classes

Jun	JUL	Aug
	02
2016	2017	2018

Connection

Summary

Nested classes

Constants

Public constructors

Public methods

Inherited methods

Constants

CAPABILITY_CANNOT_DOWNGRADE_VIDEO_TO_AUDIO

CAPABILITY_CAN_PAUSE_VIDEO

CAPABILITY_CAN_PULL_CALL

CAPABILITY_CAN_SEND_RESPONSE_VIA_CONNECTION

CAPABILITY_CAN_UPGRADE_TO_VIDEO

CAPABILITY_DISCONNECT_FROM_CONFERENCE

CAPABILITY_HOLD

CAPABILITY_MANAGE_CONFERENCE

CAPABILITY_MERGE_CONFERENCE

CAPABILITY_MUTE

CAPABILITY_RESPOND_VIA_TEXT

CAPABILITY_SEPARATE_FROM_CONFERENCE

CAPABILITY_SUPPORTS_VT_LOCAL_BIDIRECTIONAL

CAPABILITY_SUPPORTS_VT_LOCAL_RX

CAPABILITY_SUPPORTS_VT_LOCAL_TX

CAPABILITY_SUPPORTS_VT_REMOTE_BIDIRECTIONAL

CAPABILITY_SUPPORTS_VT_REMOTE_RX

CAPABILITY_SUPPORTS_VT_REMOTE_TX

CAPABILITY_SUPPORT_HOLD

CAPABILITY_SWAP_CONFERENCE

EVENT_CALL_MERGE_FAILED

EVENT_CALL_PULL_FAILED

EXTRA_ANSWERING_DROPS_FG_CALL

EXTRA_ANSWERING_DROPS_FG_CALL_APP_NAME

EXTRA_CALL_SUBJECT

EXTRA_CHILD_ADDRESS

EXTRA_LAST_FORWARDED_NUMBER

PROPERTY_HAS_CDMA_VOICE_PRIVACY

PROPERTY_IS_EXTERNAL_CALL

PROPERTY_SELF_MANAGED

STATE_ACTIVE

STATE_DIALING

STATE_DISCONNECTED

STATE_HOLDING

STATE_INITIALIZING

STATE_NEW

STATE_PULLING_CALL

STATE_RINGING

Public constructors

Connection

Public methods

capabilitiesToString

createCanceledConnection

createFailedConnection

destroy

getAddress

getAddressPresentation

getAudioModeIsVoip

getCallAudioState

getCallerDisplayName

getCallerDisplayNamePresentation

getConference

getConferenceables

getConnectionCapabilities

getConnectionProperties

getDisconnectCause

getExtras

getState

getStatusHints

getVideoProvider

isRingbackRequested

onAbort

onAnswer

onAnswer

onCallAudioStateChanged

onCallEvent

onDisconnect

onExtrasChanged

onHold

onPlayDtmfTone

onPostDialContinue

onPullExternalCall