diff options
author | Treehugger Robot <treehugger-gerrit@google.com> | 2018-03-07 19:33:52 +0000 |
---|---|---|
committer | Gerrit Code Review <noreply-gerritcodereview@google.com> | 2018-03-07 19:33:52 +0000 |
commit | 8882c55b216ae41aca28c385116dc622590cf276 (patch) | |
tree | e84ba304e9755a000fe479c2593ebde43fa82a7c | |
parent | 888c45b4847d6df3618e004011c0e1f449865cdc (diff) | |
parent | 9d12773b51eb409ae0424e162957da87c033cbfa (diff) | |
download | base-8882c55b216ae41aca28c385116dc622590cf276.tar.gz |
Merge "API Documentation and Constant cleanup."
-rw-r--r-- | api/current.txt | 8 | ||||
-rw-r--r-- | telecomm/java/android/telecom/Call.java | 137 | ||||
-rw-r--r-- | telecomm/java/android/telecom/ConnectionService.java | 98 | ||||
-rw-r--r-- | telecomm/java/android/telecom/TelecomManager.java | 24 | ||||
-rw-r--r-- | telecomm/java/android/telecom/VideoProfile.java | 1 |
5 files changed, 227 insertions, 41 deletions
diff --git a/api/current.txt b/api/current.txt index 2f669e91631d..65dcae2d4683 100644 --- a/api/current.txt +++ b/api/current.txt @@ -39192,10 +39192,10 @@ package android.telecom { method public void onStateChanged(android.telecom.Call, int); method public void onVideoCallChanged(android.telecom.Call, android.telecom.InCallService.VideoCall); field public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1; // 0x1 - field public static final int HANDOVER_FAILURE_DEST_INVALID_PERM = 3; // 0x3 - field public static final int HANDOVER_FAILURE_DEST_NOT_SUPPORTED = 2; // 0x2 - field public static final int HANDOVER_FAILURE_DEST_USER_REJECTED = 4; // 0x4 - field public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 5; // 0x5 + field public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2; // 0x2 + field public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 4; // 0x4 + field public static final int HANDOVER_FAILURE_UNKNOWN = 5; // 0x5 + field public static final int HANDOVER_FAILURE_USER_REJECTED = 3; // 0x3 } public static class Call.Details { diff --git a/telecomm/java/android/telecom/Call.java b/telecomm/java/android/telecom/Call.java index a79f2c9eaf17..73243d2ebada 100644 --- a/telecomm/java/android/telecom/Call.java +++ b/telecomm/java/android/telecom/Call.java @@ -879,42 +879,76 @@ public final class Call { /** * @hide */ - @IntDef({HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_DEST_NOT_SUPPORTED, - HANDOVER_FAILURE_DEST_INVALID_PERM, HANDOVER_FAILURE_DEST_USER_REJECTED, - HANDOVER_FAILURE_ONGOING_EMERG_CALL}) + @IntDef(prefix = { "HANDOVER_" }, + value = {HANDOVER_FAILURE_DEST_APP_REJECTED, HANDOVER_FAILURE_NOT_SUPPORTED, + HANDOVER_FAILURE_USER_REJECTED, HANDOVER_FAILURE_ONGOING_EMERG_CALL, + HANDOVER_FAILURE_UNKNOWN}) @Retention(RetentionPolicy.SOURCE) public @interface HandoverFailureErrors {} /** * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the app - * to handover the call rejects handover. + * to handover the call to rejects the handover request. + * <p> + * Will be returned when {@link Call#handoverTo(PhoneAccountHandle, int, Bundle)} is called + * and the destination {@link PhoneAccountHandle}'s {@link ConnectionService} returns a + * {@code null} {@link Connection} from + * {@link ConnectionService#onCreateOutgoingHandoverConnection(PhoneAccountHandle, + * ConnectionRequest)}. + * <p> + * For more information on call handovers, see + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}. */ public static final int HANDOVER_FAILURE_DEST_APP_REJECTED = 1; /** - * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there is - * an error associated with unsupported handover. - */ - public static final int HANDOVER_FAILURE_DEST_NOT_SUPPORTED = 2; - - /** - * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there - * are some permission errors associated with APIs doing handover. + * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover + * is initiated but the source or destination app does not support handover. + * <p> + * Will be returned when a handover is requested via + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)} and the destination + * {@link PhoneAccountHandle} does not declare + * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}. May also be returned when a handover is + * requested at the {@link PhoneAccountHandle} for the current call (i.e. the source call's + * {@link Details#getAccountHandle()}) does not declare + * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}. + * <p> + * For more information on call handovers, see + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}. */ - public static final int HANDOVER_FAILURE_DEST_INVALID_PERM = 3; + public static final int HANDOVER_FAILURE_NOT_SUPPORTED = 2; /** - * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when user - * rejects handover. + * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when the remote + * user rejects the handover request. + * <p> + * For more information on call handovers, see + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}. */ - public static final int HANDOVER_FAILURE_DEST_USER_REJECTED = 4; + public static final int HANDOVER_FAILURE_USER_REJECTED = 3; /** * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when there * is ongoing emergency call. + * <p> + * This error code is returned when {@link #handoverTo(PhoneAccountHandle, int, Bundle)} is + * called on an emergency call, or if any other call is an emergency call. + * <p> + * Handovers are not permitted while there are ongoing emergency calls. + * <p> + * For more information on call handovers, see + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}. */ - public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 5; + public static final int HANDOVER_FAILURE_ONGOING_EMERG_CALL = 4; + /** + * Handover failure reason returned via {@link #onHandoverFailed(Call, int)} when a handover + * fails for an unknown reason. + * <p> + * For more information on call handovers, see + * {@link #handoverTo(PhoneAccountHandle, int, Bundle)}. + */ + public static final int HANDOVER_FAILURE_UNKNOWN = 5; /** * Invoked when the state of this {@code Call} has changed. See {@link #getState()}. @@ -1055,6 +1089,10 @@ public final class Call { /** * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount} * has completed successfully. + * <p> + * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + * * @param call The call which had initiated handover. */ public void onHandoverComplete(Call call) {} @@ -1062,8 +1100,12 @@ public final class Call { /** * Invoked when Call handover from one {@link PhoneAccount} to other {@link PhoneAccount} * has failed. + * <p> + * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + * * @param call The call which had initiated handover. - * @param failureReason Error reason for failure + * @param failureReason Error reason for failure. */ public void onHandoverFailed(Call call, @HandoverFailureErrors int failureReason) {} } @@ -1260,7 +1302,7 @@ public final class Call { * Instructs this {@link #STATE_RINGING} {@code Call} to answer. * @param videoState The video state in which to answer the call. */ - public void answer(int videoState) { + public void answer(@VideoProfile.VideoState int videoState) { mInCallAdapter.answerCall(mTelecomCallId, videoState); } @@ -1474,16 +1516,65 @@ public final class Call { * by {@code toHandle}. The videoState specified indicates the desired video state after the * handover. * <p> - * A handover request is initiated by the user from one app to indicate a desire - * to handover a call to another. + * 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 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. + * <p> + * When this method is called on the <em>initiating</em> device, the Telecom framework will bind + * to the {@link ConnectionService} defined by the {@code toHandle} {@link PhoneAccountHandle} + * and invoke + * {@link 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 {@link 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. + * <p> + * The destination app is responsible for communicating the handover request from the + * <em>initiating</em> device to the <em>receiving</em> device. + * <p> + * When the app on the <em>receiving</em> device receives the handover request, it calls + * {@link 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. + * <p> + * When the destination app on the <em>receiving</em> device calls + * {@link TelecomManager#acceptHandover(Uri, int, PhoneAccountHandle)}, Telecom will bind to its + * {@link ConnectionService} and call + * {@link ConnectionService#onCreateIncomingHandoverConnection(PhoneAccountHandle, + * ConnectionRequest)} to inform it of the handover request. The app returns an instance of + * {@link Connection} to represent the handover call. + * <p> + * If the user of the <em>receiving</em> device accepts the handover, the app calls + * {@link Connection#setActive()} to complete the handover process; Telecom will disconnect the + * original call. If the user rejects the handover, the app calls + * {@link Connection#setDisconnected(DisconnectCause)} and specifies a {@link DisconnectCause} + * of {@link DisconnectCause#CANCELED} to indicate that the handover has been cancelled. + * <p> + * Telecom will only allow handovers from {@link PhoneAccount}s which declare + * {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_FROM}. Similarly, the {@link PhoneAccount} + * specified by {@code toHandle} must declare {@link PhoneAccount#EXTRA_SUPPORTS_HANDOVER_TO}. + * <p> + * Errors in the handover process are reported to the {@link InCallService} via + * {@link Callback#onHandoverFailed(Call, int)}. Errors in the handover process are reported to + * the involved {@link ConnectionService}s via + * {@link ConnectionService#onHandoverFailed(ConnectionRequest, int)}. * * @param toHandle {@link PhoneAccountHandle} of the {@link ConnectionService} to handover * this call to. - * @param videoState Indicates the video state desired after the handover. + * @param videoState Indicates the video state desired after the handover (see the + * {@code STATE_*} constants defined in {@link VideoProfile}). * @param extras Bundle containing extra information to be passed to the * {@link ConnectionService} */ - public void handoverTo(PhoneAccountHandle toHandle, int videoState, Bundle extras) { + public void handoverTo(PhoneAccountHandle toHandle, @VideoProfile.VideoState int videoState, + Bundle extras) { mInCallAdapter.handoverTo(mTelecomCallId, toHandle, videoState, extras); } diff --git a/telecomm/java/android/telecom/ConnectionService.java b/telecomm/java/android/telecom/ConnectionService.java index 593e12b073bc..2fdbc7194af8 100644 --- a/telecomm/java/android/telecom/ConnectionService.java +++ b/telecomm/java/android/telecom/ConnectionService.java @@ -2218,12 +2218,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}. + * <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) { @@ -2231,12 +2269,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}. + * <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) { @@ -2246,11 +2318,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} + * <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; } diff --git a/telecomm/java/android/telecom/TelecomManager.java b/telecomm/java/android/telecom/TelecomManager.java index c848f77c2c0e..4b1f0ade82da 100644 --- a/telecomm/java/android/telecom/TelecomManager.java +++ b/telecomm/java/android/telecom/TelecomManager.java @@ -1786,8 +1786,25 @@ public class TelecomManager { } /** - * Called from the recipient side of a handover to indicate a desire to accept the handover - * of an ongoing call to another {@link ConnectionService} identified by + * Called by an app to indicate that it wishes to accept the handover of an ongoing call to a + * {@link PhoneAccountHandle} it defines. + * <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> + * For a full discussion of the handover process and the APIs involved, see + * {@link android.telecom.Call#handoverTo(PhoneAccountHandle, int, Bundle)}. + * <p> + * This method is called from the <em>receiving</em> side of a handover to indicate a desire to + * accept the handover of an ongoing call to another {@link ConnectionService} identified by * {@link PhoneAccountHandle} destAcct. For managed {@link ConnectionService}s, the specified * {@link PhoneAccountHandle} must have been registered with {@link #registerPhoneAccount} and * the user must have enabled the corresponding {@link PhoneAccount}. This can be checked using @@ -1811,7 +1828,8 @@ public class TelecomManager { * @param videoState Video state after the handover. * @param destAcct The {@link PhoneAccountHandle} registered to the calling package. */ - public void acceptHandover(Uri srcAddr, int videoState, PhoneAccountHandle destAcct) { + public void acceptHandover(Uri srcAddr, @VideoProfile.VideoState int videoState, + PhoneAccountHandle destAcct) { try { if (isServiceConnected()) { getTelecomService().acceptHandover(srcAddr, videoState, destAcct); diff --git a/telecomm/java/android/telecom/VideoProfile.java b/telecomm/java/android/telecom/VideoProfile.java index e0e3a085315a..90ed36f19dbf 100644 --- a/telecomm/java/android/telecom/VideoProfile.java +++ b/telecomm/java/android/telecom/VideoProfile.java @@ -62,6 +62,7 @@ public class VideoProfile implements Parcelable { @Retention(RetentionPolicy.SOURCE) @IntDef( flag = true, + prefix = { "STATE_" }, value = {STATE_AUDIO_ONLY, STATE_TX_ENABLED, STATE_RX_ENABLED, STATE_BIDIRECTIONAL, STATE_PAUSED}) public @interface VideoState {} |