Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3a09dc18 authored by Tyler Gunn's avatar Tyler Gunn
Browse files

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.
Fixes: 73751004
Fixes: 73750515
Fixes: 73750817
Merged-In: I7860fcd813f25adaaccf632f2c61dd4138a0a889
Change-Id: I7860fcd813f25adaaccf632f2c61dd4138a0a889
(cherry picked from commit c7a86b14)
parent b8d85373

api/current.txt

+4 −4
Original line number Diff line number Diff line
@@ -41379,10 +41379,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 {

























telecomm/java/android/telecom/Call.java



+114
−23




























Original line number
Diff line number
Diff line








@@ -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);















    }

















































telecomm/java/android/telecom/ConnectionService.java



+87
−11




























Original line number
Diff line number
Diff line








@@ -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}.













     * <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 @@ 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) {









@@ -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}













     * <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;















    }

















































telecomm/java/android/telecom/TelecomManager.java



+21
−3




























Original line number
Diff line number
Diff line








@@ -1794,8 +1794,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









@@ -1819,7 +1836,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);

































telecomm/java/android/telecom/VideoProfile.java



+1
−0




























Original line number
Diff line number
Diff line








@@ -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 {}