Merge "Improve DisconnectCause API for mainline." into main

2 files changed, 62 insertions, 34 deletions

diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index fbcadd80aca9..7aeecbfeb3ad 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -13936,9 +13936,8 @@ package android.telecom {
   }
 
   @FlaggedApi("com.android.server.telecom.flags.telecom_resolve_hidden_dependencies") public static final class DisconnectCause.Builder {
-    ctor public DisconnectCause.Builder();
+    ctor public DisconnectCause.Builder(int);
     method @NonNull public android.telecom.DisconnectCause build();
-    method @NonNull public android.telecom.DisconnectCause.Builder setCode(int);
     method @NonNull public android.telecom.DisconnectCause.Builder setDescription(@Nullable CharSequence);
     method @NonNull public android.telecom.DisconnectCause.Builder setImsReasonInfo(@Nullable android.telephony.ims.ImsReasonInfo);
     method @NonNull public android.telecom.DisconnectCause.Builder setLabel(@Nullable CharSequence);
diff --git a/telecomm/java/android/telecom/DisconnectCause.java b/telecomm/java/android/telecom/DisconnectCause.java
index 5ba5ee8836e1..8b9a93bd92a4 100644
--- a/telecomm/java/android/telecom/DisconnectCause.java
+++ b/telecomm/java/android/telecom/DisconnectCause.java
@@ -16,6 +16,8 @@
 
 package android.telecom;
 
+import static java.lang.annotation.RetentionPolicy.SOURCE;
+
 import android.annotation.FlaggedApi;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
@@ -28,8 +30,11 @@ import android.telephony.PreciseDisconnectCause;
 import android.telephony.ims.ImsReasonInfo;
 import android.text.TextUtils;
 
+import androidx.annotation.IntDef;
+
 import com.android.server.telecom.flags.Flags;
 
+import java.lang.annotation.Retention;
 import java.util.Objects;
 
 /**
@@ -42,48 +47,69 @@ import java.util.Objects;
 public final class DisconnectCause implements Parcelable {
 
     /** Disconnected because of an unknown or unspecified reason. */
-    public static final int UNKNOWN = TelecomProtoEnums.UNKNOWN; // = 0
+    public static final int UNKNOWN = 0;
     /** Disconnected because there was an error, such as a problem with the network. */
-    public static final int ERROR = TelecomProtoEnums.ERROR; // = 1
+    public static final int ERROR = 1;
     /** Disconnected because of a local user-initiated action, such as hanging up. */
-    public static final int LOCAL = TelecomProtoEnums.LOCAL; // = 2
+    public static final int LOCAL = 2;
     /**
      * Disconnected because the remote party hung up an ongoing call, or because an outgoing call
      * was not answered by the remote party.
      */
-    public static final int REMOTE = TelecomProtoEnums.REMOTE; // = 3
+    public static final int REMOTE = 3;
     /** Disconnected because it has been canceled. */
-    public static final int CANCELED = TelecomProtoEnums.CANCELED; // = 4
+    public static final int CANCELED = 4;
     /** Disconnected because there was no response to an incoming call. */
-    public static final int MISSED = TelecomProtoEnums.MISSED; // = 5
+    public static final int MISSED = 5;
     /** Disconnected because the user rejected an incoming call. */
-    public static final int REJECTED = TelecomProtoEnums.REJECTED; // = 6
+    public static final int REJECTED = 6;
     /** Disconnected because the other party was busy. */
-    public static final int BUSY = TelecomProtoEnums.BUSY; // = 7
+    public static final int BUSY = 7;
     /**
      * Disconnected because of a restriction on placing the call, such as dialing in airplane
      * mode.
      */
-    public static final int RESTRICTED = TelecomProtoEnums.RESTRICTED; // = 8
+    public static final int RESTRICTED = 8;
     /** Disconnected for reason not described by other disconnect codes. */
-    public static final int OTHER = TelecomProtoEnums.OTHER; // = 9
+    public static final int OTHER = 9;
     /**
      * Disconnected because the connection manager did not support the call. The call will be tried
      * again without a connection manager. See {@link PhoneAccount#CAPABILITY_CONNECTION_MANAGER}.
      */
-    public static final int CONNECTION_MANAGER_NOT_SUPPORTED =
-            TelecomProtoEnums.CONNECTION_MANAGER_NOT_SUPPORTED; // = 10
+    public static final int CONNECTION_MANAGER_NOT_SUPPORTED = 10;
 
     /**
      * Disconnected because the user did not locally answer the incoming call, but it was answered
      * on another device where the call was ringing.
      */
-    public static final int ANSWERED_ELSEWHERE = TelecomProtoEnums.ANSWERED_ELSEWHERE; // = 11
+    public static final int ANSWERED_ELSEWHERE = 11;
 
     /**
      * Disconnected because the call was pulled from the current device to another device.
      */
-    public static final int CALL_PULLED = TelecomProtoEnums.CALL_PULLED; // = 12
+    public static final int CALL_PULLED = 12;
+
+    /**
+     * @hide
+     */
+    @Retention(SOURCE)
+    @FlaggedApi(Flags.FLAG_TELECOM_RESOLVE_HIDDEN_DEPENDENCIES)
+    @IntDef({
+            UNKNOWN,
+            ERROR,
+            LOCAL,
+            REMOTE,
+            CANCELED,
+            MISSED,
+            REJECTED,
+            BUSY,
+            RESTRICTED,
+            OTHER,
+            CONNECTION_MANAGER_NOT_SUPPORTED,
+            ANSWERED_ELSEWHERE,
+            CALL_PULLED
+    })
+    public @interface DisconnectCauseCode {}
 
     /**
      * Reason code (returned via {@link #getReason()}) which indicates that a call could not be
@@ -116,7 +142,7 @@ public final class DisconnectCause implements Parcelable {
      */
     public static final String REASON_EMERGENCY_CALL_PLACED = "REASON_EMERGENCY_CALL_PLACED";
 
-    private int mDisconnectCode;
+    private @DisconnectCauseCode int mDisconnectCode;
     private CharSequence mDisconnectLabel;
     private CharSequence mDisconnectDescription;
     private String mDisconnectReason;
@@ -130,7 +156,7 @@ public final class DisconnectCause implements Parcelable {
      *
      * @param code The code for the disconnect cause.
      */
-    public DisconnectCause(int code) {
+    public DisconnectCause(@DisconnectCauseCode int code) {
         this(code, null, null, null, ToneGenerator.TONE_UNKNOWN);
     }
 
@@ -140,7 +166,7 @@ public final class DisconnectCause implements Parcelable {
      * @param code The code for the disconnect cause.
      * @param reason The reason for the disconnect.
      */
-    public DisconnectCause(int code, String reason) {
+    public DisconnectCause(@DisconnectCauseCode int code, String reason) {
         this(code, null, null, reason, ToneGenerator.TONE_UNKNOWN);
     }
 
@@ -152,7 +178,8 @@ public final class DisconnectCause implements Parcelable {
      * @param description The localized description to show to the user to explain the disconnect.
      * @param reason The reason for the disconnect.
      */
-    public DisconnectCause(int code, CharSequence label, CharSequence description, String reason) {
+    public DisconnectCause(@DisconnectCauseCode int code, CharSequence label,
+            CharSequence description, String reason) {
         this(code, label, description, reason, ToneGenerator.TONE_UNKNOWN);
     }
 
@@ -165,8 +192,8 @@ public final class DisconnectCause implements Parcelable {
      * @param reason The reason for the disconnect.
      * @param toneToPlay The tone to play on disconnect, as defined in {@link ToneGenerator}.
      */
-    public DisconnectCause(int code, CharSequence label, CharSequence description, String reason,
-            int toneToPlay) {
+    public DisconnectCause(@DisconnectCauseCode int code, CharSequence label,
+            CharSequence description, String reason, int toneToPlay) {
         this(code, label, description, reason, toneToPlay,
                 android.telephony.DisconnectCause.ERROR_UNSPECIFIED,
                 PreciseDisconnectCause.ERROR_UNSPECIFIED, null /* imsReasonInfo */);
@@ -186,8 +213,8 @@ public final class DisconnectCause implements Parcelable {
      * @param imsReasonInfo The relevant {@link ImsReasonInfo}, or {@code null} if not available.
      * @hide
      */
-    public DisconnectCause(int code, @NonNull CharSequence label,
-            @NonNull CharSequence description, @NonNull String reason,
+    public DisconnectCause(@DisconnectCauseCode int code, @Nullable CharSequence label,
+            @Nullable CharSequence description, @Nullable String reason,
             int toneToPlay, @Annotation.DisconnectCauses int telephonyDisconnectCause,
             @Annotation.PreciseDisconnectCauses int telephonyPreciseDisconnectCause,
             @Nullable ImsReasonInfo imsReasonInfo) {
@@ -206,7 +233,7 @@ public final class DisconnectCause implements Parcelable {
      *
      * @return The disconnect code.
      */
-    public int getCode() {
+    public @DisconnectCauseCode int getCode() {
         return mDisconnectCode;
     }
 
@@ -301,28 +328,24 @@ public final class DisconnectCause implements Parcelable {
     @SystemApi
     @FlaggedApi(Flags.FLAG_TELECOM_RESOLVE_HIDDEN_DEPENDENCIES)
     public static final class Builder {
-        private int mDisconnectCode;
+        private @DisconnectCauseCode int mDisconnectCode;
         private CharSequence mDisconnectLabel;
         private CharSequence mDisconnectDescription;
         private String mDisconnectReason;
-        private int mToneToPlay;
+        private int mToneToPlay = ToneGenerator.TONE_UNKNOWN;
         private int mTelephonyDisconnectCause;
         private int mTelephonyPreciseDisconnectCause;
         private ImsReasonInfo mImsReasonInfo;
 
-        /**
-         * Sets the code for the reason for this disconnect.
-         * @param code The code denoting the type of disconnect.
-         */
-        public @NonNull DisconnectCause.Builder setCode(int code) {
+        public Builder(@DisconnectCauseCode int code) {
             mDisconnectCode = code;
-            return this;
         }
 
         /**
          * Sets a label which explains the reason for the disconnect cause, used for display in the
          * user interface.
          * @param label The label to associate with the disconnect cause.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setLabel(@Nullable CharSequence label) {
             mDisconnectLabel = label;
@@ -333,6 +356,7 @@ public final class DisconnectCause implements Parcelable {
          * Sets a description which provides the reason for the disconnect cause, used for display
          * in the user interface.
          * @param description The description to associate with the disconnect cause.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setDescription(
                 @Nullable CharSequence description) {
@@ -344,6 +368,7 @@ public final class DisconnectCause implements Parcelable {
          * Sets a reason providing explanation for the disconnect (intended for logging and not for
          * displaying in the user interface).
          * @param reason The reason for the disconnect.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setReason(@NonNull String reason) {
             mDisconnectReason = reason;
@@ -353,6 +378,7 @@ public final class DisconnectCause implements Parcelable {
         /**
          * Sets the tone to play when disconnected.
          * @param toneToPlay The tone as defined in {@link ToneGenerator} to play when disconnected.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setTone(int toneToPlay) {
             mToneToPlay = toneToPlay;
@@ -363,6 +389,7 @@ public final class DisconnectCause implements Parcelable {
          * Sets the telephony {@link android.telephony.DisconnectCause} for the call (used
          * internally by Telecom for providing extra debug information from Telephony).
          * @param telephonyDisconnectCause The disconnect cause as provided by Telephony.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setTelephonyDisconnectCause(
                 @Annotation.DisconnectCauses int telephonyDisconnectCause) {
@@ -375,6 +402,7 @@ public final class DisconnectCause implements Parcelable {
          * internally by Telecom for providing extra debug information from Telephony).
          * @param telephonyPreciseDisconnectCause The precise disconnect cause as provided by
          *                                        Telephony.
+         * @return The {@link DisconnectCause} builder instance.
          */
 
         public @NonNull DisconnectCause.Builder setTelephonyPreciseDisconnectCause(
@@ -384,10 +412,11 @@ public final class DisconnectCause implements Parcelable {
         }
 
         /**
-         * Returns the telephony {@link ImsReasonInfo} associated with the call disconnection. This
+         * Sets the telephony {@link ImsReasonInfo} associated with the call disconnection. This
          * is only used internally by Telecom for providing extra debug information from Telephony.
          *
          * @param imsReasonInfo The {@link ImsReasonInfo} or {@code null} if not known.
+         * @return The {@link DisconnectCause} builder instance.
          */
         public @NonNull DisconnectCause.Builder setImsReasonInfo(
                 @Nullable ImsReasonInfo imsReasonInfo) {