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, 37 insertions, 16 deletions

diff --git a/framework/java/android/bluetooth/BluetoothHealth.java b/framework/java/android/bluetooth/BluetoothHealth.java
index 5fd60e0016..65f68a943e 100644
--- a/framework/java/android/bluetooth/BluetoothHealth.java
+++ b/framework/java/android/bluetooth/BluetoothHealth.java
@@ -16,6 +16,10 @@
 
 package android.bluetooth;
 
+import android.annotation.RequiresPermission;
+import android.annotation.SuppressLint;
+import android.bluetooth.annotations.RequiresBluetoothConnectPermission;
+import android.bluetooth.annotations.RequiresLegacyBluetoothPermission;
 import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
@@ -111,8 +115,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      * which will act as the {@link #SOURCE_ROLE}. This is an asynchronous call and so
      * the callback is used to notify success or failure if the function returns true.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * @param name The friendly name associated with the application or configuration.
      * @param dataType The dataType of the Source role of Health Profile to which the sink wants to
      * connect to.
@@ -126,6 +128,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * {@link BluetoothDevice#createL2capChannel(int)}
      */
     @Deprecated
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public boolean registerSinkAppConfiguration(String name, int dataType,
             BluetoothHealthCallback callback) {
         Log.e(TAG, "registerSinkAppConfiguration(): BluetoothHealth is deprecated");
@@ -136,8 +142,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      * Unregister an application configuration that has been registered using
      * {@link #registerSinkAppConfiguration}
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * @param config The health app configuration
      * @return Success or failure.
      *
@@ -147,6 +151,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * {@link BluetoothDevice#createL2capChannel(int)}
      */
     @Deprecated
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public boolean unregisterAppConfiguration(BluetoothHealthAppConfiguration config) {
         Log.e(TAG, "unregisterAppConfiguration(): BluetoothHealth is deprecated");
         return false;
@@ -157,8 +165,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      * This is an asynchronous call. If this function returns true, the callback
      * associated with the application configuration will be called.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * @param device The remote Bluetooth device.
      * @param config The application configuration which has been registered using {@link
      * #registerSinkAppConfiguration(String, int, BluetoothHealthCallback) }
@@ -170,6 +176,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * {@link BluetoothDevice#createL2capChannel(int)}
      */
     @Deprecated
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public boolean connectChannelToSource(BluetoothDevice device,
             BluetoothHealthAppConfiguration config) {
         Log.e(TAG, "connectChannelToSource(): BluetoothHealth is deprecated");
@@ -181,8 +191,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      * This is an asynchronous call. If this function returns true, the callback
      * associated with the application configuration will be called.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * @param device The remote Bluetooth device.
      * @param config The application configuration which has been registered using {@link
      * #registerSinkAppConfiguration(String, int, BluetoothHealthCallback) }
@@ -195,6 +203,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * {@link BluetoothDevice#createL2capChannel(int)}
      */
     @Deprecated
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public boolean disconnectChannel(BluetoothDevice device,
             BluetoothHealthAppConfiguration config, int channelId) {
         Log.e(TAG, "disconnectChannel(): BluetoothHealth is deprecated");
@@ -205,8 +217,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      * Get the file descriptor of the main channel associated with the remote device
      * and application configuration.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * <p> Its the responsibility of the caller to close the ParcelFileDescriptor
      * when done.
      *
@@ -220,6 +230,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * {@link BluetoothDevice#createL2capChannel(int)}
      */
     @Deprecated
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public ParcelFileDescriptor getMainChannelFd(BluetoothDevice device,
             BluetoothHealthAppConfiguration config) {
         Log.e(TAG, "getMainChannelFd(): BluetoothHealth is deprecated");
@@ -229,8 +243,6 @@ public final class BluetoothHealth implements BluetoothProfile {
     /**
      * Get the current connection state of the profile.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * This is not specific to any application configuration but represents the connection
      * state of the local Bluetooth adapter with the remote device. This can be used
      * by applications like status bar which would just like to know the state of the
@@ -241,6 +253,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * #STATE_CONNECTING}, {@link #STATE_DISCONNECTED}, {@link #STATE_DISCONNECTING}
      */
     @Override
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public int getConnectionState(BluetoothDevice device) {
         Log.e(TAG, "getConnectionState(): BluetoothHealth is deprecated");
         return STATE_DISCONNECTED;
@@ -251,8 +267,6 @@ public final class BluetoothHealth implements BluetoothProfile {
      *
      * <p> Return the set of devices which are in state {@link #STATE_CONNECTED}
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     *
      * This is not specific to any application configuration but represents the connection
      * state of the local Bluetooth adapter for this profile. This can be used
      * by applications like status bar which would just like to know the state of the
@@ -261,6 +275,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * @return List of devices. The list will be empty on error.
      */
     @Override
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public List<BluetoothDevice> getConnectedDevices() {
         Log.e(TAG, "getConnectedDevices(): BluetoothHealth is deprecated");
         return new ArrayList<>();
@@ -273,8 +291,7 @@ public final class BluetoothHealth implements BluetoothProfile {
      * <p> If none of the devices match any of the given states,
      * an empty list will be returned.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
-     * This is not specific to any application configuration but represents the connection
+     * <p>This is not specific to any application configuration but represents the connection
      * state of the local Bluetooth adapter for this profile. This can be used
      * by applications like status bar which would just like to know the state of the
      * local adapter.
@@ -284,6 +301,10 @@ public final class BluetoothHealth implements BluetoothProfile {
      * @return List of devices. The list will be empty on error.
      */
     @Override
+    @RequiresLegacyBluetoothPermission
+    @RequiresBluetoothConnectPermission
+    @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
+    @SuppressLint("AndroidFrameworkRequiresPermission")
     public List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states) {
         Log.e(TAG, "getDevicesMatchingConnectionStates(): BluetoothHealth is deprecated");
         return new ArrayList<>();