Make vibrator effect queries an @IntDef.

Rather than tri-state enums, which aren't as clear and easy to
mis-interpret, switch the return values to an explicit tri-state
@IntDef.

Bug: 150958120
Test: atest VibratorTest
Change-Id: I3a5daa4078a21008664ea14d45a5c5284c1224ed

5 files changed, 90 insertions, 39 deletions

diff --git a/api/current.txt b/api/current.txt
index bf4093435fad..461bc5f006f6 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -37158,9 +37158,9 @@ package android.os {
   }
 
   public abstract class Vibrator {
-    method @Nullable public final Boolean areAllEffectsSupported(@NonNull int...);
+    method public final int areAllEffectsSupported(@NonNull int...);
     method public final boolean areAllPrimitivesSupported(@NonNull int...);
-    method @Nullable public boolean[] areEffectsSupported(@NonNull int...);
+    method @NonNull public int[] areEffectsSupported(@NonNull int...);
     method @NonNull public boolean[] arePrimitivesSupported(@NonNull int...);
     method @RequiresPermission(android.Manifest.permission.VIBRATE) public abstract void cancel();
     method public abstract boolean hasAmplitudeControl();
@@ -37171,6 +37171,9 @@ package android.os {
     method @Deprecated @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(long[], int, android.media.AudioAttributes);
     method @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(android.os.VibrationEffect);
     method @RequiresPermission(android.Manifest.permission.VIBRATE) public void vibrate(android.os.VibrationEffect, android.media.AudioAttributes);
+    field public static final int VIBRATION_EFFECT_SUPPORT_NO = 2; // 0x2
+    field public static final int VIBRATION_EFFECT_SUPPORT_UNKNOWN = 0; // 0x0
+    field public static final int VIBRATION_EFFECT_SUPPORT_YES = 1; // 0x1
   }
 
   public class WorkSource implements android.os.Parcelable {
diff --git a/core/java/android/os/IVibratorService.aidl b/core/java/android/os/IVibratorService.aidl
index 84013e7ebc88..615ae6593330 100644
--- a/core/java/android/os/IVibratorService.aidl
+++ b/core/java/android/os/IVibratorService.aidl
@@ -28,7 +28,7 @@ interface IVibratorService
     boolean registerVibratorStateListener(in IVibratorStateListener listener);
     boolean unregisterVibratorStateListener(in IVibratorStateListener listener);
     boolean hasAmplitudeControl();
-    boolean[] areEffectsSupported(in int[] effectIds);
+    int[] areEffectsSupported(in int[] effectIds);
     boolean[] arePrimitivesSupported(in int[] primitiveIds);
     boolean setAlwaysOnEffect(int uid, String opPkg, int alwaysOnId, in VibrationEffect effect,
             in VibrationAttributes attributes);
diff --git a/core/java/android/os/SystemVibrator.java b/core/java/android/os/SystemVibrator.java
index da20c7f2ae70..2dba8dce62da 100644
--- a/core/java/android/os/SystemVibrator.java
+++ b/core/java/android/os/SystemVibrator.java
@@ -21,12 +21,13 @@ import android.annotation.NonNull;
 import android.compat.annotation.UnsupportedAppUsage;
 import android.content.Context;
 import android.media.AudioAttributes;
-import android.os.IVibratorStateListener;
 import android.util.ArrayMap;
 import android.util.Log;
+
 import com.android.internal.annotations.GuardedBy;
-import java.util.concurrent.Executor;
+
 import java.util.Objects;
+import java.util.concurrent.Executor;
 
 /**
  * Vibrator implementation that controls the main system vibrator.
@@ -238,13 +239,13 @@ public class SystemVibrator extends Vibrator {
     }
 
     @Override
-    public boolean[] areEffectsSupported(@VibrationEffect.EffectType int... effectIds) {
+    public int[] areEffectsSupported(@VibrationEffect.EffectType int... effectIds) {
         try {
             return mService.areEffectsSupported(effectIds);
         } catch (RemoteException e) {
             Log.w(TAG, "Failed to query effect support");
+            throw e.rethrowAsRuntimeException();
         }
-        return new boolean[effectIds.length];
     }
 
     @Override
@@ -254,8 +255,8 @@ public class SystemVibrator extends Vibrator {
             return mService.arePrimitivesSupported(primitiveIds);
         } catch (RemoteException e) {
             Log.w(TAG, "Failed to query effect support");
+            throw e.rethrowAsRuntimeException();
         }
-        return new boolean[primitiveIds.length];
     }
 
 
diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java
index f7183b14a97a..86d009e8607e 100644
--- a/core/java/android/os/Vibrator.java
+++ b/core/java/android/os/Vibrator.java
@@ -32,6 +32,7 @@ import android.util.Log;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.util.Arrays;
 import java.util.concurrent.Executor;
 
 /**
@@ -72,6 +73,37 @@ public abstract class Vibrator {
      */
     public static final int VIBRATION_INTENSITY_HIGH = 3;
 
+    /**
+     * Vibration effect support: unknown
+     *
+     * The hardware doesn't report it's supported effects, so we can't determine whether the
+     * effect is supported or not.
+     */
+    public static final int VIBRATION_EFFECT_SUPPORT_UNKNOWN = 0;
+
+    /**
+     * Vibration effect support: supported
+     *
+     * This effect is supported by the underlying hardware.
+     */
+    public static final int VIBRATION_EFFECT_SUPPORT_YES = 1;
+
+    /**
+     * Vibration effect support: unsupported
+     *
+     * This effect is <b>not</b> supported by the underlying hardware.
+     */
+    public static final int VIBRATION_EFFECT_SUPPORT_NO = 2;
+
+    /** @hide */
+    @Retention(RetentionPolicy.SOURCE)
+    @IntDef(prefix = {"VIBRATION_EFFECT_SUPPORT_"}, value = {
+            VIBRATION_EFFECT_SUPPORT_UNKNOWN,
+            VIBRATION_EFFECT_SUPPORT_YES,
+            VIBRATION_EFFECT_SUPPORT_NO,
+    })
+    public @interface VibrationEffectSupport {}
+
     /** @hide */
     @Retention(RetentionPolicy.SOURCE)
     @IntDef(prefix = {"VIBRATION_INTENSITY_"}, value = {
@@ -318,47 +350,61 @@ public abstract class Vibrator {
     /**
      * Query whether the vibrator supports the given effects.
      *
-     * If the returned array is {@code null}, the hardware doesn't support querying its supported
-     * effects. It may support any or all effects, but there's no way to programmatically know
-     * whether a {@link #vibrate} call will be successful.
+     * Not all hardware reports its effect capabilities, so the system may not necessarily know
+     * whether an effect is supported or not.
      *
-     * If the returned array is non-null, then it will be the same length as the query array and
-     * the value at a given index will contain whether the effect at that same index in the
-     * querying array is supported or not.
+     * The returned array will be the same length as the query array and the value at a given index
+     * will contain {@link #VIBRATION_EFFECT_SUPPORT_YES} if the effect at that same index in the
+     * querying array is supported, {@link #VIBRATION_EFFECT_SUPPORT_NO} if it isn't supported, or
+     * {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN} if the system can't determine whether it's
+     * supported or not.
      *
      * @param effectIds Which effects to query for.
-     * @return Whether the effects are supported. Null when the hardware doesn't tell us what it
-     *         supports.
+     * @return An array containing the systems current knowledge about whether the given effects
+     * are supported or not.
      */
-    @Nullable
-    public boolean[] areEffectsSupported(
+    @NonNull
+    @VibrationEffectSupport
+    public int[] areEffectsSupported(
             @NonNull @VibrationEffect.EffectType int... effectIds) {
-        return new boolean[effectIds.length];
+        final int[] support = new int[effectIds.length];
+        Arrays.fill(support, VIBRATION_EFFECT_SUPPORT_NO);
+        return support;
     }
 
     /**
      * Query whether the vibrator supports all of the given effects.
      *
-     * If the result is {@code null}, the hardware doesn't support querying its supported
-     * effects. It may support any or all effects, but there's no way to programmatically know
-     * whether a {@link #vibrate} call will be successful.
+     * Not all hardware reports its effect capabilities, so the system may not necessarily know
+     * whether an effect is supported or not.
      *
-     * If the returned array is non-null, then it will return whether all of the effects are
+     * If the result is {@link #VIBRATION_EFFECT_SUPPORT_YES}, all effects in the query are
      * supported by the hardware.
      *
+     * If the result is {@link #VIBRATION_EFFECT_SUPPORT_NO}, at least one of the effects in the
+     * query is not supported.
+     *
+     * If the result is {@link #VIBRATION_EFFECT_SUPPORT_UNKNOWN}, the system doesn't know whether
+     * all of the effects are supported. It may support any or all of the queried effects,
+     * but there's no way to programmatically know whether a {@link #vibrate} call will successfully
+     * cause a vibration. It's guaranteed, however, that none of the queried effects are
+     * definitively unsupported by the hardware.
+     *
      * @param effectIds Which effects to query for.
-     * @return Whether the effects are supported. {@code null} when the hardware doesn't tell us
-     *         what it supports.
+     * @return Whether all of the effects are supported.
      */
-    @Nullable
-    public final Boolean areAllEffectsSupported(
+    @VibrationEffectSupport
+    public final int areAllEffectsSupported(
             @NonNull @VibrationEffect.EffectType int... effectIds) {
-        for (boolean supported : areEffectsSupported(effectIds)) {
-            if (!supported) {
-                return false;
+        int support = VIBRATION_EFFECT_SUPPORT_YES;
+        for (int supported : areEffectsSupported(effectIds)) {
+            if (supported == VIBRATION_EFFECT_SUPPORT_NO) {
+                return VIBRATION_EFFECT_SUPPORT_NO;
+            } else if (supported == VIBRATION_EFFECT_SUPPORT_UNKNOWN) {
+                support = VIBRATION_EFFECT_SUPPORT_UNKNOWN;
             }
         }
-        return true;
+        return support;
     }
 
 
diff --git a/services/core/java/com/android/server/VibratorService.java b/services/core/java/com/android/server/VibratorService.java
index dd9cc641f2dd..ac4a42ca7024 100644
--- a/services/core/java/com/android/server/VibratorService.java
+++ b/services/core/java/com/android/server/VibratorService.java
@@ -605,15 +605,16 @@ public class VibratorService extends IVibratorService.Stub
     }
 
     @Override // Binder call
-    public boolean[] areEffectsSupported(int[] effectIds) {
-        // Return null to indicate that the HAL doesn't actually tell us what effects are
-        // supported.
+    public int[] areEffectsSupported(int[] effectIds) {
+        int[] supported = new int[effectIds.length];
         if (mSupportedEffects == null) {
-            return null;
-        }
-        boolean[] supported = new boolean[effectIds.length];
-        for (int i = 0; i < effectIds.length; i++) {
-            supported[i] = mSupportedEffects.contains(effectIds[i]);
+            Arrays.fill(supported, Vibrator.VIBRATION_EFFECT_SUPPORT_UNKNOWN);
+        } else {
+            for (int i = 0; i < effectIds.length; i++) {
+                supported[i] = mSupportedEffects.contains(effectIds[i])
+                        ? Vibrator.VIBRATION_EFFECT_SUPPORT_YES
+                        : Vibrator.VIBRATION_EFFECT_SUPPORT_NO;
+            }
         }
         return supported;
     }