Merge "API review : use a range of numbers for OEM errors" into sc-dev

3 files changed, 38 insertions, 29 deletions

diff --git a/core/java/android/service/voice/AlwaysOnHotwordDetector.java b/core/java/android/service/voice/AlwaysOnHotwordDetector.java
index e8130172221a..fed28df964d6 100644
--- a/core/java/android/service/voice/AlwaysOnHotwordDetector.java
+++ b/core/java/android/service/voice/AlwaysOnHotwordDetector.java
@@ -49,7 +49,6 @@ import android.os.ParcelFileDescriptor;
 import android.os.PersistableBundle;
 import android.os.RemoteException;
 import android.os.SharedMemory;
-import android.service.voice.HotwordDetectionService.InitializationStatus;
 import android.util.Log;
 import android.util.Slog;
 
@@ -531,9 +530,12 @@ public class AlwaysOnHotwordDetector extends AbstractHotwordDetector {
          * Called when the {@link HotwordDetectionService} is created by the system and given a
          * short amount of time to report it's initialization state.
          *
-         * @param status Info about initialization state of {@link HotwordDetectionService}.
+         * @param status Info about initialization state of {@link HotwordDetectionService}; the
+         * allowed values are {@link HotwordDetectionService#INITIALIZATION_STATUS_SUCCESS},
+         * 1<->{@link HotwordDetectionService#getMaxCustomInitializationStatus()},
+         * {@link HotwordDetectionService#INITIALIZATION_STATUS_UNKNOWN}.
          */
-        public void onHotwordDetectionServiceInitialized(@InitializationStatus int status) {
+        public void onHotwordDetectionServiceInitialized(int status) {
         }
 
         /**
diff --git a/core/java/android/service/voice/HotwordDetectionService.java b/core/java/android/service/voice/HotwordDetectionService.java
index ea01e09ef0de..3960e3864e1f 100644
--- a/core/java/android/service/voice/HotwordDetectionService.java
+++ b/core/java/android/service/voice/HotwordDetectionService.java
@@ -78,30 +78,17 @@ public abstract class HotwordDetectionService extends Service {
     /** @hide */
     public static final String KEY_INITIALIZATION_STATUS = "initialization_status";
 
-    /** @hide */
-    @Retention(RetentionPolicy.SOURCE)
-    @IntDef(flag = true, prefix = { "INITIALIZATION_STATUS_" }, value = {
-            INITIALIZATION_STATUS_SUCCESS,
-            INITIALIZATION_STATUS_CUSTOM_ERROR_1,
-            INITIALIZATION_STATUS_CUSTOM_ERROR_2,
-            INITIALIZATION_STATUS_UNKNOWN,
-    })
-    public @interface InitializationStatus {}
-
     /**
-     * Indicates that the updated status is successful.
-     */
-    public static final int INITIALIZATION_STATUS_SUCCESS = 0;
-
-    /**
-     * Indicates that the updated status is failure for some application specific reasons.
+     * The maximum number of initialization status for some application specific failed reasons.
+     *
+     * @hide
      */
-    public static final int INITIALIZATION_STATUS_CUSTOM_ERROR_1 = 1;
+    public static final int MAXIMUM_NUMBER_OF_INITIALIZATION_STATUS_CUSTOM_ERROR = 2;
 
     /**
-     * Indicates that the updated status is failure for some application specific reasons.
+     * Indicates that the updated status is successful.
      */
-    public static final int INITIALIZATION_STATUS_CUSTOM_ERROR_2 = 2;
+    public static final int INITIALIZATION_STATUS_SUCCESS = 0;
 
     /**
      * Indicates that the callback wasn’t invoked within the timeout.
@@ -229,6 +216,19 @@ public abstract class HotwordDetectionService extends Service {
     }
 
     /**
+     * Returns the maximum number of initialization status for some application specific failed
+     * reasons.
+     *
+     * Note: The value 0 is reserved for success.
+     *
+     * @hide
+     */
+    @SystemApi
+    public static int getMaxCustomInitializationStatus() {
+        return MAXIMUM_NUMBER_OF_INITIALIZATION_STATUS_CUSTOM_ERROR;
+    }
+
+    /**
      * Called when the device hardware (such as a DSP) detected the hotword, to request second stage
      * validation before handing over the audio to the {@link AlwaysOnHotwordDetector}.
      * <p>
@@ -298,9 +298,10 @@ public abstract class HotwordDetectionService extends Service {
      * such data to the trusted process.
      * @param callbackTimeoutMillis Timeout in milliseconds for the operation to invoke the
      * statusCallback.
-     * @param statusCallback Use this to return the updated result. This is non-null only when the
-     * {@link HotwordDetectionService} is being initialized; and it is null if the state is updated
-     * after that.
+     * @param statusCallback Use this to return the updated result; the allowed values are
+     * {@link #INITIALIZATION_STATUS_SUCCESS}, 1<->{@link #getMaxCustomInitializationStatus()}.
+     * This is non-null only when the {@link HotwordDetectionService} is being initialized; and it
+     * is null if the state is updated after that.
      *
      * @hide
      */
@@ -309,7 +310,7 @@ public abstract class HotwordDetectionService extends Service {
             @Nullable PersistableBundle options,
             @Nullable SharedMemory sharedMemory,
             @DurationMillisLong long callbackTimeoutMillis,
-            @Nullable @InitializationStatus IntConsumer statusCallback) {
+            @Nullable IntConsumer statusCallback) {
         // TODO: Handle the unimplemented case by throwing?
     }
 
@@ -389,6 +390,10 @@ public abstract class HotwordDetectionService extends Service {
         if (callback != null) {
             intConsumer =
                     value -> {
+                        if (value > getMaxCustomInitializationStatus()) {
+                            throw new IllegalArgumentException(
+                                    "The initialization status is invalid for " + value);
+                        }
                         try {
                             Bundle status = new Bundle();
                             status.putInt(KEY_INITIALIZATION_STATUS, value);
diff --git a/core/java/android/service/voice/HotwordDetector.java b/core/java/android/service/voice/HotwordDetector.java
index d3c10ea7c670..b2f810aac09e 100644
--- a/core/java/android/service/voice/HotwordDetector.java
+++ b/core/java/android/service/voice/HotwordDetector.java
@@ -28,7 +28,6 @@ import android.media.AudioFormat;
 import android.os.ParcelFileDescriptor;
 import android.os.PersistableBundle;
 import android.os.SharedMemory;
-import android.service.voice.HotwordDetectionService.InitializationStatus;
 
 /**
  * Basic functionality for hotword detectors.
@@ -166,9 +165,12 @@ public interface HotwordDetector {
          * Called when the {@link HotwordDetectionService} is created by the system and given a
          * short amount of time to report it's initialization state.
          *
-         * @param status Info about initialization state of {@link HotwordDetectionService}.
+         * @param status Info about initialization state of {@link HotwordDetectionService}; the
+         * allowed values are {@link HotwordDetectionService#INITIALIZATION_STATUS_SUCCESS},
+         * 1<->{@link HotwordDetectionService#getMaxCustomInitializationStatus()},
+         * {@link HotwordDetectionService#INITIALIZATION_STATUS_UNKNOWN}.
          */
-        void onHotwordDetectionServiceInitialized(@InitializationStatus int status);
+        void onHotwordDetectionServiceInitialized(int status);
 
         /**
          * Called with the {@link HotwordDetectionService} is restarted.