Update Bluetooth API annotations.

Recent work has introduced a new "Nearby devices" runtime permission
which protects all existing Bluetooth APIs; we've done this by
defining a <split-permission> to convert the old BLUETOOTH and
BLUETOOTH_ADMIN permissions into one of three new permissions:

* BLUETOOTH_ADVERTISE: Required to be able to advertise to nearby
                       Bluetooth devices.
* BLUETOOTH_CONNECT:   Allows applications to connect to paired
                       bluetooth devices.
* BLUETOOTH_SCAN:      Required to be able to discover and pair
                       nearby Bluetooth devices.

At its core, this change begins updating the Bluetooth APIs to have
correct @RequiresPermission indicating which permission is actually
enforced internally.  To ensure alignment across Binder, the newly
added "RequiresPermissionChecker" Error Prone checker was used to
discover any inconsistencies, ensuring correctness from server-side
enforcement up through to the public APIs.

In addition, since developers will continue building apps for both
modern and legacy platforms, this change introduces new auto-doc
annotations which will emit helpful consistent documentation
describing the behavior of older devices that are still using the
old permission model.

Bug: 183626724
Test: ./build/soong/soong_ui.bash --make-mode Bluetooth RUN_ERROR_PRONE=true
Change-Id: I02aa127e8e07f239561f4f2a3bbdfc6fccb82f7f

1 files changed, 25 insertions, 7 deletions

diff --git a/framework/java/android/bluetooth/le/AdvertisingSet.java b/framework/java/android/bluetooth/le/AdvertisingSet.java
index 1df35e1e38..54a18e6f1d 100644
--- a/framework/java/android/bluetooth/le/AdvertisingSet.java
+++ b/framework/java/android/bluetooth/le/AdvertisingSet.java
@@ -16,9 +16,12 @@
 
 package android.bluetooth.le;
 
+import android.annotation.RequiresPermission;
 import android.bluetooth.BluetoothAdapter;
 import android.bluetooth.IBluetoothGatt;
 import android.bluetooth.IBluetoothManager;
+import android.bluetooth.annotations.RequiresBluetoothAdvertisePermission;
+import android.bluetooth.annotations.RequiresLegacyBluetoothAdminPermission;
 import android.os.RemoteException;
 import android.util.Log;
 
@@ -27,9 +30,6 @@ import android.util.Log;
  * <p>
  * To get an instance of {@link AdvertisingSet}, call the
  * {@link BluetoothLeAdvertiser#startAdvertisingSet} method.
- * <p>
- * <b>Note:</b> Most of the methods here require {@link android.Manifest.permission#BLUETOOTH_ADMIN}
- * permission.
  *
  * @see AdvertiseData
  */
@@ -58,8 +58,6 @@ public final class AdvertisingSet {
     /**
      * Enables Advertising. This method returns immediately, the operation status is
      * delivered through {@code callback.onAdvertisingEnabled()}.
-     * <p>
-     * Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
      *
      * @param enable whether the advertising should be enabled (true), or disabled (false)
      * @param duration advertising duration, in 10ms unit. Valid range is from 1 (10ms) to 65535
@@ -68,6 +66,9 @@ public final class AdvertisingSet {
      * controller shall attempt to send prior to terminating the extended advertising, even if the
      * duration has not expired. Valid range is from 1 to 255.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void enableAdvertising(boolean enable, int duration,
             int maxExtendedAdvertisingEvents) {
         try {
@@ -90,6 +91,9 @@ public final class AdvertisingSet {
      * three bytes will be added for flags. If the update takes place when the advertising set is
      * enabled, the data can be maximum 251 bytes long.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setAdvertisingData(AdvertiseData advertiseData) {
         try {
             mGatt.setAdvertisingData(mAdvertiserId, advertiseData);
@@ -107,6 +111,9 @@ public final class AdvertisingSet {
      * exceed {@link BluetoothAdapter#getLeMaximumAdvertisingDataLength}. If the update takes place
      * when the advertising set is enabled, the data can be maximum 251 bytes long.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setScanResponseData(AdvertiseData scanResponse) {
         try {
             mGatt.setScanResponseData(mAdvertiserId, scanResponse);
@@ -122,6 +129,9 @@ public final class AdvertisingSet {
      *
      * @param parameters advertising set parameters.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setAdvertisingParameters(AdvertisingSetParameters parameters) {
         try {
             mGatt.setAdvertisingParameters(mAdvertiserId, parameters);
@@ -135,6 +145,9 @@ public final class AdvertisingSet {
      * periodic advertising is not enabled. This method returns immediately, the operation
      * status is delivered through {@code callback.onPeriodicAdvertisingParametersUpdated()}.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setPeriodicAdvertisingParameters(PeriodicAdvertisingParameters parameters) {
         try {
             mGatt.setPeriodicAdvertisingParameters(mAdvertiserId, parameters);
@@ -153,6 +166,9 @@ public final class AdvertisingSet {
      * BluetoothAdapter#getLeMaximumAdvertisingDataLength}. If the update takes place when the
      * periodic advertising is enabled for this set, the data can be maximum 251 bytes long.
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setPeriodicAdvertisingData(AdvertiseData periodicData) {
         try {
             mGatt.setPeriodicAdvertisingData(mAdvertiserId, periodicData);
@@ -168,6 +184,9 @@ public final class AdvertisingSet {
      * @param enable whether the periodic advertising should be enabled (true), or disabled
      * (false).
      */
+    @RequiresLegacyBluetoothAdminPermission
+    @RequiresBluetoothAdvertisePermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_ADVERTISE)
     public void setPeriodicAdvertisingEnabled(boolean enable) {
         try {
             mGatt.setPeriodicAdvertisingEnable(mAdvertiserId, enable);
@@ -181,10 +200,9 @@ public final class AdvertisingSet {
      * This method is exposed only for Bluetooth PTS tests, no app or system service
      * should ever use it.
      *
-     * This method requires {@link android.Manifest.permission#BLUETOOTH_PRIVILEGED} permission.
-     *
      * @hide
      */
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_PRIVILEGED)
     public void getOwnAddress() {
         try {
             mGatt.getOwnAddress(mAdvertiserId);