From 9d12773b51eb409ae0424e162957da87c033cbfa Mon Sep 17 00:00:00 2001 From: Tyler Gunn Date: Fri, 2 Mar 2018 15:45:51 -0800 Subject: API Documentation and Constant cleanup. 1. Update handover API docs for clarity. 2. Added an unknown value per API review comments. 3. Renamed HANDOVER_FAILURE_DEST_USER_REJECTED to HANDOVER_FAILURE_USER_REJECTED 3. Removed the HANDOVER_FAILURE_DEST_INVALID_PERM constant since it isn't used (methods which deal with permissions throw security exceptions). Test: Make doc and verify documentation. Change-Id: Id21d6b4c83d5c773ab38d78eb6b1886a1ac4dadf Fixes: 73751004 Fixes: 73750515 Fixes: 73750817 --- .../java/android/telecom/ConnectionService.java | 98 +++++++++++++++++++--- 1 file changed, 87 insertions(+), 11 deletions(-) (limited to 'telecomm/java/android/telecom/ConnectionService.java') diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java index 2ea7e65eeec7..09e7f709fa99 100644 --- a/telecomm/java/android/telecom/ConnectionService.java +++ b/telecomm/java/android/telecom/ConnectionService.java @@ -2219,12 +2219,50 @@ public abstract class ConnectionService extends Service { } /** - * Called by Telecom on the initiating side of the handover to create an instance of a - * handover connection. + * Called by Telecom to request that a {@link ConnectionService} creates an instance of an + * outgoing handover {@link Connection}. + *

+ * A call handover is the process where an ongoing call is transferred from one app (i.e. + * {@link 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 initiating device is where a user initiated + * the handover process (e.g. by calling {@link android.telecom.Call#handoverTo( + * PhoneAccountHandle, int, Bundle)}, and the other device is considered the receiving + * device. + *

+ * This method is called on the destination {@link ConnectionService} on initiating + * device when the user initiates a handover request from one app to another. The user request + * originates in the {@link InCallService} via + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + *

+ * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + *

+ * Implementations of this method should return an instance of {@link Connection} which + * represents the handover. If your app does not wish to accept a handover to it at this time, + * you can return {@code null}. The code below shows an example of how this is done. + * 

+     * {@code
+     * public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
+     *     fromPhoneAccountHandle, ConnectionRequest request) {
+     *   if (!isHandoverAvailable()) {
+     *       return null;
+     *   }
+     *   MyConnection connection = new MyConnection();
+     *   connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
+     *   connection.setVideoState(request.getVideoState());
+     *   return connection;
+     * }
+     * }
+     *
+ * * @param fromPhoneAccountHandle {@link PhoneAccountHandle} associated with the * ConnectionService which needs to handover the call. - * @param request Details about the call which needs to be handover. - * @return Connection object corresponding to the handover call. + * @param request Details about the call to handover. + * @return {@link Connection} instance corresponding to the handover call. */ public Connection onCreateOutgoingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request) { @@ -2232,12 +2270,46 @@ public abstract class ConnectionService extends Service { } /** - * Called by Telecom on the receiving side of the handover to request the - * {@link ConnectionService} to create an instance of a handover connection. + * Called by Telecom to request that a {@link ConnectionService} creates an instance of an + * incoming handover {@link Connection}. + *

+ * A call handover is the process where an ongoing call is transferred from one app (i.e. + * {@link 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 initiating device is where a user initiated + * the handover process (e.g. by calling {@link android.telecom.Call#handoverTo( + * PhoneAccountHandle, int, Bundle)}, and the other device is considered the receiving + * device. + *

+ * This method is called on the destination app on the receiving device when the + * destination app calls {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to + * accept an incoming handover from the initiating device. + *

+ * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + *

+ * Implementations of this method should return an instance of {@link Connection} which + * represents the handover. The code below shows an example of how this is done. + * 

+     * {@code
+     * public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle
+     *     fromPhoneAccountHandle, ConnectionRequest request) {
+     *   // Given that your app requested to accept the handover, you should not return null here.
+     *   MyConnection connection = new MyConnection();
+     *   connection.setAddress(request.getAddress(), TelecomManager.PRESENTATION_ALLOWED);
+     *   connection.setVideoState(request.getVideoState());
+     *   return connection;
+     * }
+     * }
+     *
+ * * @param fromPhoneAccountHandle {@link PhoneAccountHandle} associated with the * ConnectionService which needs to handover the call. * @param request Details about the call which needs to be handover. - * @return {@link Connection} object corresponding to the handover call. + * @return {@link Connection} instance corresponding to the handover call. */ public Connection onCreateIncomingHandoverConnection(PhoneAccountHandle fromPhoneAccountHandle, ConnectionRequest request) { @@ -2247,11 +2319,15 @@ public abstract class ConnectionService extends Service { /** * Called by Telecom in response to a {@code TelecomManager#acceptHandover()} * invocation which failed. - * @param request Details about the call which needs to be handover. - * @param error Reason for handover failure as defined in - * {@link android.telecom.Call.Callback#HANDOVER_FAILURE_DEST_INVALID_PERM} + *

+ * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)} + * + * @param request Details about the call which failed to handover. + * @param error Reason for handover failure. Will be one of the */ - public void onHandoverFailed(ConnectionRequest request, int error) { + public void onHandoverFailed(ConnectionRequest request, + @Call.Callback.HandoverFailureErrors int error) { return; } -- cgit v1.2.3