Update API docs to indicate that BT addresses are to be provided in big

endian.

Tag: #feature
Bug: 233217148
Test: Manual (docs change)
Ignore-AOSP-First: Android T docs change
Change-Id: Iee36345088c886d5b43120bb10d8ddf52133de07

2 files changed, 42 insertions, 39 deletions

diff --git a/framework/java/android/bluetooth/BluetoothAdapter.java b/framework/java/android/bluetooth/BluetoothAdapter.java
index eed12635c5..e4bfc42b86 100644
--- a/framework/java/android/bluetooth/BluetoothAdapter.java
+++ b/framework/java/android/bluetooth/BluetoothAdapter.java
@@ -1005,8 +1005,8 @@ public final class BluetoothAdapter {
     /**
      * Get a {@link BluetoothDevice} object for the given Bluetooth hardware
      * address.
-     * <p>Valid Bluetooth hardware addresses must be upper case, in a format
-     * such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is
+     * <p>Valid Bluetooth hardware addresses must be upper case, in big endian byte order, and in a
+     * format such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is
      * available to validate a Bluetooth address.
      * <p>A {@link BluetoothDevice} will always be returned for a valid
      * hardware address, even if this adapter has never seen that device.
@@ -1024,8 +1024,8 @@ public final class BluetoothAdapter {
     /**
      * Get a {@link BluetoothDevice} object for the given Bluetooth hardware
      * address and addressType.
-     * <p>Valid Bluetooth hardware addresses must be upper case, in a format
-     * such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is
+     * <p>Valid Bluetooth hardware addresses must be upper case, in big endian byte order, and in a
+     * format such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is
      * available to validate a Bluetooth address.
      * <p>A {@link BluetoothDevice} will always be returned for a valid
      * hardware address and type, even if this adapter has never seen that device.
diff --git a/framework/java/android/bluetooth/le/ScanFilter.java b/framework/java/android/bluetooth/le/ScanFilter.java
index 3edde10f96..ee65f168be 100644
--- a/framework/java/android/bluetooth/le/ScanFilter.java
+++ b/framework/java/android/bluetooth/le/ScanFilter.java
@@ -690,13 +690,15 @@ public final class ScanFilter implements Parcelable {
         }
 
         /**
-         * Set filter on device address.
+         * Set a scan filter on the remote device address.
+         * <p>
+         * The address passed to this API must be in big endian byte order. It needs to be in the
+         * format of "01:02:03:AB:CD:EF". The device address can be validated using
+         * {@link BluetoothAdapter#checkBluetoothAddress}. The @AddressType is defaulted to
+         * {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC}.
          *
-         * @param deviceAddress The device Bluetooth address for the filter. It needs to be in the
-         * format of "01:02:03:AB:CD:EF". The device address can be validated using {@link
-         * BluetoothAdapter#checkBluetoothAddress}.  The @AddressType is defaulted to {@link
-         * BluetoothDevice#ADDRESS_TYPE_PUBLIC}
-         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid.
+         * @param deviceAddress the remote device Bluetooth address for the filter
+         * @throws IllegalArgumentException if the {@code deviceAddress} is invalid
          */
         public Builder setDeviceAddress(String deviceAddress) {
             if (deviceAddress == null) {
@@ -707,20 +709,20 @@ public final class ScanFilter implements Parcelable {
         }
 
         /**
-         * Set filter on Address with AddressType
-         *
-         * <p>This key is used to resolve a private address from a public address.
+         * Set a scan filter on the remote device address with an address type.
+         * <p>
+         * The address passed to this API must be in big endian byte order. It needs to be in the
+         * format of "01:02:03:AB:CD:EF". The device address can be validated using
+         * {@link BluetoothAdapter#checkBluetoothAddress}.
          *
-         * @param deviceAddress The device Bluetooth address for the filter. It needs to be in the
-         * format of "01:02:03:AB:CD:EF". The device address can be validated using {@link
-         * BluetoothAdapter#checkBluetoothAddress}. May be any type of address.
+         * @param deviceAddress the remote device Bluetooth address for the filter
          * @param addressType indication of the type of address
-         * e.g. {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC}
-         * or {@link BluetoothDevice#ADDRESS_TYPE_RANDOM}
          *
-         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid.
-         * @throws IllegalArgumentException If the {@code addressType} is invalid length
-         * @throws NullPointerException if {@code deviceAddress} is null.
+         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid
+         * @throws IllegalArgumentException If the {@code addressType} is invalid length or is not
+         * either {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC} or
+         * {@link BluetoothDevice#ADDRESS_TYPE_RANDOM}
+         * @throws NullPointerException if {@code deviceAddress} is null
          *
          * @hide
          */
@@ -732,25 +734,25 @@ public final class ScanFilter implements Parcelable {
         }
 
         /**
-         * Set filter on Address with AddressType and the Identity Resolving Key (IRK).
-         *
-         * <p>The IRK is used to resolve a {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC} from
-         * a PRIVATE_ADDRESS type.
+         * Set a scan filter on the remote device address with an address type and the Identity
+         * Resolving Key (IRK).
+         * <p>
+         * The address passed to this API must be either a public or random static address in big
+         * endian byte order. It needs to be in the format of "01:02:03:AB:CD:EF". The device
+         * address can be validated using {@link BluetoothAdapter#checkBluetoothAddress}.
+         * <p>
+         * The IRK is used to resolve a static address from a private address. The IRK must be
+         * provided in big endian byte order.
          *
-         * @param deviceAddress The device Bluetooth address for the filter. It needs to be in the
-         * format of "01:02:03:AB:CD:EF". The device address can be validated using {@link
-         * BluetoothAdapter#checkBluetoothAddress}.  This Address type must only be PUBLIC OR RANDOM
-         * STATIC.
+         * @param deviceAddress the remote device Bluetooth address for the filter
          * @param addressType indication of the type of address
-         * e.g. {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC}
-         * or {@link BluetoothDevice#ADDRESS_TYPE_RANDOM}
          * @param irk non-null byte array representing the Identity Resolving Key
          *
-         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid.
-         * @throws IllegalArgumentException if the {@code irk} is invalid length.
-         * @throws IllegalArgumentException If the {@code addressType} is invalid length or is not
-         * PUBLIC or RANDOM STATIC when an IRK is present.
-         * @throws NullPointerException if {@code deviceAddress} or {@code irk} is null.
+         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid
+         * @throws IllegalArgumentException if the {@code irk} is invalid length
+         * @throws IllegalArgumentException If the {@code addressType} is an invalid length or is
+         * not PUBLIC or RANDOM STATIC
+         * @throws NullPointerException if {@code deviceAddress} or {@code irk} is null
          *
          * @hide
          */
@@ -779,9 +781,10 @@ public final class ScanFilter implements Parcelable {
          * @param irk non-null byte array representing the Identity Resolving Address; nullable
          * internally.
          *
-         * @throws IllegalArgumentException If the {@code deviceAddress} is invalid.
-         * @throws IllegalArgumentException If the {@code addressType} is invalid length.
-         * @throws NullPointerException if {@code deviceAddress} is null.
+         * @throws IllegalArgumentException if the {@code deviceAddress} is invalid
+         * @throws IllegalArgumentException if the {@code addressType} is not PUBLIC or RANDOM
+         * STATIC when an IRK is present
+         * @throws NullPointerException if {@code deviceAddress} is null
          *
          * @hide
          */