Call.HandoverTo(PhoneAccountHandle, VideoProfileState, Bundle) Method

Definition

Namespace:

Android.Telecom

Assembly:

Mono.Android.dll

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

[Android.Runtime.Register("handoverTo", "(Landroid/telecom/PhoneAccountHandle;ILandroid/os/Bundle;)V", "", ApiSince=28)]
public void HandoverTo (Android.Telecom.PhoneAccountHandle? toHandle, Android.Telecom.VideoProfileState videoState, Android.OS.Bundle? extras);

[<Android.Runtime.Register("handoverTo", "(Landroid/telecom/PhoneAccountHandle;ILandroid/os/Bundle;)V", "", ApiSince=28)>]
member this.HandoverTo : Android.Telecom.PhoneAccountHandle * Android.Telecom.VideoProfileState * Android.OS.Bundle -> unit

Parameters

toHandle

PhoneAccountHandle

PhoneAccountHandle of the ConnectionService to handover this call to.

videoState

VideoProfileState

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

extras

Bundle

Bundle containing extra information to be passed to the ConnectionService

Attributes

RegisterAttribute

Remarks

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 <em>initiating</em> device (since the user initiates the handover from this device), and the other device is considered the <em>receiving</em> device.

When this method is called on the <em>initiating</em> device, the Telecom framework will bind to the ConnectionService defined by the toHandlePhoneAccountHandle and invoke ConnectionService#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 <em>initiating</em> device to the <em>receiving</em> device.

When the app on the <em>receiving</em> device receives the handover request, it calls TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle) to continue the handover process from the <em>initiating</em> device to the <em>receiving</em> device. At this point the destination app on the <em>receiving</em> 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 <em>receiving</em> device calls TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle), Telecom will bind to its ConnectionService and call ConnectionService#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 <em>receiving</em> 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).

Java documentation for android.telecom.Call.handoverTo(android.telecom.PhoneAccountHandle, int, android.os.Bundle).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.