From b15909f4c4dbc2e4c6092fac8245b6523bf233a9 Mon Sep 17 00:00:00 2001
From: Lais Andrade <lsandrade@google.com>
Date: Mon, 1 Feb 2021 15:20:02 +0000
Subject: [PATCH] Add documentation to Vibrator on foreground/background app
 behavior

Add information to javadocs explaining that apps in background can only vibrate the device if the given AudioAttributes usage is one of notification, ringtone or alarm usages.

Fix: 146313440
Test: N/A
Change-Id: Iff24612ac76be6a77fbfa700ec59a2ca32b2b1b5
---
 core/java/android/os/Vibrator.java | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/core/java/android/os/Vibrator.java b/core/java/android/os/Vibrator.java
index 097b67259c4b5..75bc8af6efb1a 100644
--- a/core/java/android/os/Vibrator.java
+++ b/core/java/android/os/Vibrator.java
@@ -228,6 +228,8 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
      * @param milliseconds The number of milliseconds to vibrate.
      * @deprecated Use {@link #vibrate(VibrationEffect)} instead.
      */
@@ -240,6 +242,9 @@ public abstract class Vibrator {
     /**
      * Vibrate constantly for the specified period of time.
      *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
      * @param milliseconds The number of milliseconds to vibrate.
      * @param attributes   {@link AudioAttributes} corresponding to the vibration. For example,
      *                     specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
@@ -274,6 +279,8 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * </p>
      *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
      * @param pattern an array of longs of times for which to turn the vibrator on or off.
      * @param repeat  the index into pattern at which to repeat, or -1 if
      *                you don't want to repeat.
@@ -299,6 +306,9 @@ public abstract class Vibrator {
      * to start the repeat, or -1 to disable repeating.
      * </p>
      *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
      * @param pattern    an array of longs of times for which to turn the vibrator on or off.
      * @param repeat     the index into pattern at which to repeat, or -1 if
      *                   you don't want to repeat.
@@ -326,11 +336,30 @@ public abstract class Vibrator {
         }
     }
 
+    /**
+     * Vibrate with a given effect.
+     *
+     * <p>The app should be in foreground for the vibration to happen.</p>
+     *
+     * @param vibe {@link VibrationEffect} describing the vibration to be performed.
+     */
     @RequiresPermission(android.Manifest.permission.VIBRATE)
     public void vibrate(VibrationEffect vibe) {
         vibrate(vibe, null);
     }
 
+    /**
+     * Vibrate with a given effect.
+     *
+     * <p>The app should be in foreground for the vibration to happen. Background apps should
+     * specify a ringtone, notification or alarm usage in order to vibrate.</p>
+     *
+     * @param vibe       {@link VibrationEffect} describing the vibration to be performed.
+     * @param attributes {@link AudioAttributes} corresponding to the vibration. For example,
+     *                   specify {@link AudioAttributes#USAGE_ALARM} for alarm vibrations or
+     *                   {@link AudioAttributes#USAGE_NOTIFICATION_RINGTONE} for
+     *                   vibrations associated with incoming calls.
+     */
     @RequiresPermission(android.Manifest.permission.VIBRATE)
     public void vibrate(VibrationEffect vibe, AudioAttributes attributes) {
         vibrate(Process.myUid(), mPackageName, vibe, null, attributes);