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
diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java
index 2ea7e65..09e7f709 100644
--- a/telecomm/java/android/telecom/ConnectionService.java
+++ b/telecomm/java/android/telecom/ConnectionService.java
@@ -2219,12 +2219,50 @@
}
/**
- * 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}.
+ * <p>
+ * 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.
+ * <p>
+ * When considering a handover scenario the <em>initiating</em> 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 <em>receiving</em>
+ * device.
+ * <p>
+ * This method is called on the destination {@link ConnectionService} on <em>initiating</em>
+ * 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)}.
+ * <p>
+ * For a full discussion of the handover process and the APIs involved, see
+ * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
+ * <p>
+ * 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.
+ * <pre>
+ * {@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;
+ * }
+ * }
+ * </pre>
+ *
* @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 @@
}
/**
- * 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}.
+ * <p>
+ * 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.
+ * <p>
+ * When considering a handover scenario the <em>initiating</em> 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 <em>receiving</em>
+ * device.
+ * <p>
+ * This method is called on the destination app on the <em>receiving</em> device when the
+ * destination app calls {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)} to
+ * accept an incoming handover from the <em>initiating</em> device.
+ * <p>
+ * For a full discussion of the handover process and the APIs involved, see
+ * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}.
+ * <p>
+ * 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.
+ * <pre>
+ * {@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;
+ * }
+ * }
+ * </pre>
+ *
* @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 @@
/**
* 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}
+ * <p>
+ * 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;
}