Add connection handover APIs.

Add new call/connection event keys for handover.
Add TelecomManager extra keys used for handover.
Add PhoneAccount extra keys used to control availability of handover.

Test: Test app/harness.
Bug: 37102939
Change-Id: Icc5db7209362f04c4e3be397fee692bbf4a6a473

diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java
index b4414d5..f822d5e 100644 (file)
--- a/telecomm/java/android/telecom/Call.java
+++ b/telecomm/java/android/telecom/Call.java
@@ -132,6 +132,54 @@ public final class Call {
     public static final String EXTRA_LAST_EMERGENCY_CALLBACK_TIME_MILLIS =
             "android.telecom.extra.LAST_EMERGENCY_CALLBACK_TIME_MILLIS";
 
+    /**
+     * Call event sent from a {@link Call} via {@link #sendCallEvent(String, Bundle)} to inform
+     * Telecom that the user has requested that the current {@link Call} should be handed over
+     * to another {@link ConnectionService}.
+     * <p>
+     * The caller must specify the {@link #EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE} to indicate to
+     * Telecom which {@link PhoneAccountHandle} the {@link Call} should be handed over to.
+     * @hide
+     */
+    public static final String EVENT_REQUEST_HANDOVER =
+            "android.telecom.event.REQUEST_HANDOVER";
+
+    /**
+     * Extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event.  Specifies the
+     * {@link PhoneAccountHandle} to which a call should be handed over to.
+     * @hide
+     */
+    public static final String EXTRA_HANDOVER_PHONE_ACCOUNT_HANDLE =
+            "android.telecom.extra.HANDOVER_PHONE_ACCOUNT_HANDLE";
+
+    /**
+     * Integer extra key used with the {@link #EVENT_REQUEST_HANDOVER} call event.  Specifies the
+     * video state of the call when it is handed over to the new {@link PhoneAccount}.
+     * <p>
+     * Valid values: {@link VideoProfile#STATE_AUDIO_ONLY},
+     * {@link VideoProfile#STATE_BIDIRECTIONAL}, {@link VideoProfile#STATE_RX_ENABLED}, and
+     * {@link VideoProfile#STATE_TX_ENABLED}.
+     * @hide
+     */
+    public static final String EXTRA_HANDOVER_VIDEO_STATE =
+            "android.telecom.extra.HANDOVER_VIDEO_STATE";
+
+    /**
+     * Call event sent from Telecom via {@link Connection#onCallEvent(String, Bundle)} to
+     * inform a {@link Connection} that a handover initiated via {@link #EVENT_REQUEST_HANDOVER}
+     * has completed.
+     * @hide
+     */
+    public static final String EVENT_HANDOVER_COMPLETE = "android.telecom.event.HANDOVER_COMPLETE";
+
+    /**
+     * Call event sent from Telecom via {@link Connection#onCallEvent(String, Bundle)} to
+     * inform a {@link Connection} that a handover initiated via {@link #EVENT_REQUEST_HANDOVER}
+     * has failed to complete.
+     * @hide
+     */
+    public static final String EVENT_HANDOVER_FAILED = "android.telecom.event.HANDOVER_FAILED";
+
     public static class Details {
 
         /** Call can currently be put on hold or unheld. */

diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 7401dda..3eafaf5 100644 (file)
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -92,6 +92,32 @@ public abstract class ConnectionService extends Service {
     @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION)
     public static final String SERVICE_INTERFACE = "android.telecom.ConnectionService";
 
+    /**
+     * Boolean extra used by Telecom to inform a {@link ConnectionService} that the purpose of it
+     * being asked to create a new outgoing {@link Connection} is to perform a handover of an
+     * ongoing call on the device from another {@link PhoneAccount}/{@link ConnectionService}.  Will
+     * be specified in the {@link ConnectionRequest#getExtras()} passed by Telecom when
+     * {@link #onCreateOutgoingConnection(PhoneAccountHandle, ConnectionRequest)} is called.
+     * <p>
+     * Telecom will also specify {@link #EXTRA_HANDOVER_TOKEN} to provide a Telecom-specific opaque
+     * token representing the ongoing call which is to be handed over.
+     * <p>
+     * When your {@link ConnectionService} receives this extra, it should communicate the
+     * {@link #EXTRA_HANDOVER_TOKEN} to the other device's matching {@link ConnectionService}.  That
+     * {@link ConnectionService} will continue the handover using
+     * {@link TelecomManager#addNewIncomingCall(PhoneAccountHandle, Bundle)}, specifying
+     * {@link TelecomManager#EXTRA_IS_HANDOVER} and {@link TelecomManager#EXTRA_HANDOVER_TOKEN}.
+     * @hide
+     */
+    public static final String EXTRA_IS_HANDOVER = TelecomManager.EXTRA_IS_HANDOVER;
+
+    /**
+     * String extra used by Telecom when {@link #EXTRA_IS_HANDOVER} is true to provide an identifier
+     * for the call to be handed over.
+     * @hide
+     */
+    public static final String EXTRA_HANDOVER_TOKEN = TelecomManager.EXTRA_HANDOVER_TOKEN;
+
     // Flag controlling whether PII is emitted into the logs
     private static final boolean PII_DEBUG = Log.isLoggable(android.util.Log.DEBUG);
 

diff --git a/telecomm/java/android/telecom/PhoneAccount.java b/telecomm/java/android/telecom/PhoneAccount.java
index c42a835..080ead1 100644 (file)
--- a/telecomm/java/android/telecom/PhoneAccount.java
+++ b/telecomm/java/android/telecom/PhoneAccount.java
@@ -68,6 +68,34 @@ public final class PhoneAccount implements Parcelable {
             "android.telecom.extra.CALL_SUBJECT_CHARACTER_ENCODING";
 
     /**
+     * Boolean {@link PhoneAccount} extras key (see {@link PhoneAccount#getExtras()}) which
+     * indicates whether this {@link PhoneAccount} is capable of supporting a request to handover a
+     * connection (see {@link android.telecom.Call#EVENT_REQUEST_HANDOVER}) to this
+     * {@link PhoneAccount} from a {@link PhoneAccount} specifying
+     * {@link #EXTRA_SUPPORTS_HANDOVER_FROM}.
+     * <p>
+     * A handover request is initiated by the user from the default dialer app to indicate a desire
+     * to handover a call from one {@link PhoneAccount}/{@link ConnectionService} to another.
+     * @hide
+     */
+    public static final String EXTRA_SUPPORTS_HANDOVER_TO =
+            "android.telecom.extra.SUPPORTS_HANDOVER_TO";
+
+    /**
+     * Boolean {@link PhoneAccount} extras key (see {@link PhoneAccount#getExtras()}) which
+     * indicates whether this {@link PhoneAccount} is capable of supporting a request to handover a
+     * connection from this {@link PhoneAccount} to another {@link PhoneAccount}.
+     * (see {@link android.telecom.Call#EVENT_REQUEST_HANDOVER}) which specifies
+     * {@link #EXTRA_SUPPORTS_HANDOVER_TO}.
+     * <p>
+     * A handover request is initiated by the user from the default dialer app to indicate a desire
+     * to handover a call from one {@link PhoneAccount}/{@link ConnectionService} to another.
+     * @hide
+     */
+    public static final String EXTRA_SUPPORTS_HANDOVER_FROM =
+            "android.telecom.extra.SUPPORTS_HANDOVER_FROM";
+
+    /**
      * Flag indicating that this {@code PhoneAccount} can act as a connection manager for
      * other connections. The {@link ConnectionService} associated with this {@code PhoneAccount}
      * will be allowed to manage phone calls including using its own proprietary phone-call

diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java
index 1874d8d..8f8ba6d 100644 (file)
--- a/telecomm/java/android/telecom/TelecomManager.java
+++ b/telecomm/java/android/telecom/TelecomManager.java
@@ -338,6 +338,28 @@ public class TelecomManager {
             "android.telecom.extra.NEW_OUTGOING_CALL_CANCEL_TIMEOUT";
 
     /**
+     * Boolean extra specified when calling {@link #addNewIncomingCall(PhoneAccountHandle, Bundle)}
+     * to indicate to Telecom that the purpose of adding a new incoming call is to handover an
+     * existing call from the user's device to a different {@link PhoneAccount}.
+     * <p>
+     * The caller must also include {@link #EXTRA_HANDOVER_TOKEN} to specify which existing call is
+     * to be handed over.
+     * @hide
+     */
+    public static final String EXTRA_IS_HANDOVER = "android.telecom.extra.IS_HANDOVER";
+
+    /**
+     * String extra which identifies the existing call on the current device which will be handed
+     * over.  This is a Telecom-specific opaque token; the caller should not make any assumptions
+     * about its meaning or content.
+     * <p>
+     * Used alongside {@link #EXTRA_IS_HANDOVER} when calling
+     * {@link #addNewIncomingCall(PhoneAccountHandle, Bundle)}.
+     * @hide
+     */
+    public static final String EXTRA_HANDOVER_TOKEN = "android.telecom.extra.HANDOVER_TOKEN";
+
+    /**
      * A boolean extra, which when set on the {@link Intent#ACTION_CALL} intent or on the bundle
      * passed into {@link #placeCall(Uri, Bundle)}, indicates that the call should be initiated with
      * an RTT session open. See {@link android.telecom.Call.RttCall} for more information on RTT.