Merge "Merge TP1A.220321.002" into t-keystone-qcom-dev

1 files changed, 57 insertions, 11 deletions

diff --git a/framework/java/android/bluetooth/BluetoothDevice.java b/framework/java/android/bluetooth/BluetoothDevice.java
index f25af1d9a6..5e674890b6 100644
--- a/framework/java/android/bluetooth/BluetoothDevice.java
+++ b/framework/java/android/bluetooth/BluetoothDevice.java
@@ -54,6 +54,7 @@ package android.bluetooth;
 import static android.bluetooth.BluetoothUtils.getSyncTimeout;
 
 import android.annotation.IntDef;
+import android.annotation.IntRange;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
@@ -251,7 +252,7 @@ public final class BluetoothDevice implements Parcelable, Attributable {
      * #EXTRA_BOND_STATE} and {@link #EXTRA_PREVIOUS_BOND_STATE}.
      */
     // Note: When EXTRA_BOND_STATE is BOND_NONE then this will also
-    // contain a hidden extra field EXTRA_REASON with the result code.
+    // contain a hidden extra field EXTRA_UNBOND_REASON with the result code.
     @RequiresLegacyBluetoothPermission
     @RequiresBluetoothConnectPermission
     @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
@@ -291,6 +292,7 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     /**
      * Broadcast Action: Indicates the audio buffer size should be switched
      * between a low latency buffer size and a higher and larger latency buffer size.
+     * Only registered receivers will receive this intent.
      * <p>Always contains the extra fields {@link #EXTRA_DEVICE} and {@link
      * #EXTRA_LOW_LATENCY_BUFFER_SIZE}.
      *
@@ -523,8 +525,7 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     public static final int BOND_BONDED = 12;
 
     /**
-     * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST}
-     * intents for unbond reason.
+     * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST} intents for unbond reason.
      * Possible value are :
      *  - {@link #UNBOND_REASON_AUTH_FAILED}
      *  - {@link #UNBOND_REASON_AUTH_REJECTED}
@@ -536,11 +537,22 @@ public final class BluetoothDevice implements Parcelable, Attributable {
      *  - {@link #UNBOND_REASON_REMOTE_AUTH_CANCELED}
      *  - {@link #UNBOND_REASON_REMOVED}
      *
-     * {@hide}
+     * Note: Can be added as a hidden extra field for {@link #ACTION_BOND_STATE_CHANGED} when the
+     * {@link #EXTRA_BOND_STATE} is {@link #BOND_NONE}
+     *
+     * @hide
      */
     @SystemApi
     @SuppressLint("ActionValue")
-    public static final String EXTRA_REASON = "android.bluetooth.device.extra.REASON";
+    public static final String EXTRA_UNBOND_REASON = "android.bluetooth.device.extra.REASON";
+
+    /**
+     * Use {@link EXTRA_UNBOND_REASON} instead
+     * @hide
+     */
+    @UnsupportedAppUsage
+    public static final String EXTRA_REASON = EXTRA_UNBOND_REASON;
+
 
     /**
      * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST}
@@ -938,6 +950,15 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     /**
      * Broadcast Action: This intent is used to broadcast CONNECTION ACCESS REQUEST
      *
+     * This action will trigger a prompt for the user to accept or deny giving the
+     * permission for this device. Permissions can be specified with
+     * {@link #EXTRA_ACCESS_REQUEST_TYPE}.
+     *
+     * The reply will be an {@link #ACTION_CONNECTION_ACCESS_REPLY} sent to the specified
+     * {@link #EXTRA_PACKAGE_NAME} and {@link #EXTRA_CLASS_NAME}.
+     *
+     * This action can be cancelled with {@link #ACTION_CONNECTION_ACCESS_CANCEL}.
+     *
      * @hide
      */
     @SystemApi
@@ -951,6 +972,13 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     /**
      * Broadcast Action: This intent is used to broadcast CONNECTION ACCESS REPLY
      *
+     * This action is the reply from {@link #ACTION_CONNECTION_ACCESS_REQUEST}
+     * that is sent to the specified {@link #EXTRA_PACKAGE_NAME}
+     * and {@link #EXTRA_CLASS_NAME}.
+     *
+     * See the extra fields {@link #EXTRA_CONNECTION_ACCESS_RESULT} and
+     * {@link #EXTRA_ALWAYS_ALLOWED} for possible results.
+     *
      * @hide
      */
     @SystemApi
@@ -988,7 +1016,11 @@ public final class BluetoothDevice implements Parcelable, Attributable {
             "android.bluetooth.device.action.SILENCE_MODE_CHANGED";
 
     /**
-     * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REQUEST} intent.
+     * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REQUEST}.
+     *
+     * Possible values are {@link #REQUEST_TYPE_PROFILE_CONNECTION},
+     * {@link #REQUEST_TYPE_PHONEBOOK_ACCESS}, {@link #REQUEST_TYPE_MESSAGE_ACCESS}
+     * and {@link #REQUEST_TYPE_SIM_ACCESS}
      *
      * @hide
      */
@@ -1032,6 +1064,8 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     /**
      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REPLY} intent.
      *
+     * Possible values are {@link #CONNECTION_ACCESS_YES} and {@link #CONNECTION_ACCESS_NO}.
+     *
      * @hide
      */
     @SystemApi
@@ -1188,7 +1222,8 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     public static final int PAIRING_VARIANT_DISPLAY_PIN = 5;
 
     /**
-     * The user will be prompted to accept or deny the OOB pairing request
+     * The user will be prompted to accept or deny the OOB pairing request.
+     * This is used for Bluetooth 2.1 secure simple pairing.
      *
      * @hide
      */
@@ -1470,7 +1505,14 @@ public final class BluetoothDevice implements Parcelable, Attributable {
         mAttributionSource = attributionSource;
     }
 
-    /** {@hide} */
+    /**
+     * Method should never be used anywhere. Only exception is from {@link Intent}
+     * Used to set the device current attribution source
+     *
+     * @param attributionSource The associated {@link AttributionSource} for this device in this
+     * process
+     * @hide
+     */
     @SystemApi
     @RequiresPermission(android.Manifest.permission.BLUETOOTH_PRIVILEGED)
     public void prepareToEnterProcess(@NonNull AttributionSource attributionSource) {
@@ -1764,7 +1806,7 @@ public final class BluetoothDevice implements Parcelable, Attributable {
     @RequiresLegacyBluetoothPermission
     @RequiresBluetoothConnectPermission
     @RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
-    public int getBatteryLevel() {
+    public @IntRange(from = -100, to = 100) int getBatteryLevel() {
         if (DBG) log("getBatteryLevel()");
         final IBluetooth service = sService;
         final int defaultValue = BATTERY_LEVEL_BLUETOOTH_OFF;
@@ -2184,10 +2226,14 @@ public final class BluetoothDevice implements Parcelable, Attributable {
 
     /**
      * Disconnects all connected bluetooth profiles between the local and remote device.
-     * Disconnection is asynchronous and you should listen to each profile's broadcast intent
+     * Disconnection is asynchronous, so you should listen to each profile's broadcast intent
      * ACTION_CONNECTION_STATE_CHANGED to verify whether disconnection was successful. For example,
      * to verify a2dp is disconnected, you would listen for
-     * {@link BluetoothA2dp#ACTION_CONNECTION_STATE_CHANGED}
+     * {@link BluetoothA2dp#ACTION_CONNECTION_STATE_CHANGED}. Once all profiles have disconnected,
+     * the ACL link should come down and {@link #ACTION_ACL_DISCONNECTED} should be broadcast.
+     * <p>
+     * In the rare event that one or more profiles fail to disconnect, call this method again to
+     * send another request to disconnect each connected profile.
      *
      * @return whether the messages were successfully sent to try to disconnect all profiles
      * @throws IllegalArgumentException if the device address is invalid