From 629ba4958e1a6898b51ea19d01d6048067730052 Mon Sep 17 00:00:00 2001
From: Anh Pham <anhph@google.com>
Date: Tue, 22 Jun 2021 14:17:47 +0200
Subject: Update API doc w/ high-rate permission requirement

Test: Build successfully
Bug: 191301110
Change-Id: I653036036bea0e2889807ec44ed98206a427dfb8
---
 core/java/android/hardware/Sensor.java        | 12 ++++++++----
 core/java/android/hardware/SensorManager.java |  7 +++++++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/core/java/android/hardware/Sensor.java b/core/java/android/hardware/Sensor.java
index 37469e916eef..08f5a8a582db 100644
--- a/core/java/android/hardware/Sensor.java
+++ b/core/java/android/hardware/Sensor.java
@@ -848,8 +848,10 @@ public final class Sensor {
     /**
      * Get the highest supported direct report mode rate level of the sensor.
      *
-     * @return Highest direct report rate level of this sensor. If the sensor does not support
-     * direct report mode, this returns {@link SensorDirectChannel#RATE_STOP}.
+     * @return Highest direct report rate level of this sensor. Note that if the app does not have
+     * the {@link android.Manifest.permission#HIGH_SAMPLING_RATE_SENSORS} permission, the highest
+     * direct report rate level is {@link SensorDirectChannel#RATE_NORMAL}. If the sensor
+     * does not support direct report mode, this returns {@link SensorDirectChannel#RATE_STOP}.
      * @see SensorDirectChannel#RATE_STOP
      * @see SensorDirectChannel#RATE_NORMAL
      * @see SensorDirectChannel#RATE_FAST
@@ -1002,9 +1004,11 @@ public final class Sensor {
     }
 
     /**
-     * @return the minimum delay allowed between two events in microsecond
+     * @return the minimum delay allowed between two events in microseconds
      * or zero if this sensor only returns a value when the data it's measuring
-     * changes.
+     * changes. Note that if the app does not have the
+     * {@link android.Manifest.permission#HIGH_SAMPLING_RATE_SENSORS} permission, the
+     * minimum delay is capped at 5000 microseconds (200 Hz).
      */
     public int getMinDelay() {
         return mMinDelay;
diff --git a/core/java/android/hardware/SensorManager.java b/core/java/android/hardware/SensorManager.java
index 713b66abed21..572a8a81883a 100644
--- a/core/java/android/hardware/SensorManager.java
+++ b/core/java/android/hardware/SensorManager.java
@@ -46,6 +46,13 @@ import java.util.List;
  * at {@link TriggerEventListener}. {@link Sensor#TYPE_SIGNIFICANT_MOTION}
  * is an example of a trigger sensor.
  * </p>
+ * <p>
+ * In order to access sensor data at high sampling rates (i.e. greater than 200 Hz
+ * for {@link SensorEventListener} and greater than {@link SensorDirectChannel#RATE_NORMAL}
+ * for {@link SensorDirectChannel}), apps must declare
+ * the {@link android.Manifest.permission#HIGH_SAMPLING_RATE_SENSORS} permission
+ * in their AndroidManifest.xml file.
+ * </p>
  * <pre class="prettyprint">
  * public class SensorActivity extends Activity implements SensorEventListener {
  *     private final SensorManager mSensorManager;
-- 
cgit v1.2.3-59-g8ed1b