From 715aa0e1da6024f85b0fcdb875f4c49be5a466ed Mon Sep 17 00:00:00 2001 From: Rahul Sabnis Date: Thu, 26 May 2022 13:52:33 -0700 Subject: 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 --- .../java/android/bluetooth/BluetoothAdapter.java | 8 +-- .../java/android/bluetooth/le/ScanFilter.java | 73 +++++++++++----------- 2 files changed, 42 insertions(+), 39 deletions(-) (limited to 'framework/java') 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. - *

Valid Bluetooth hardware addresses must be upper case, in a format - * such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is + *

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. *

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. - *

Valid Bluetooth hardware addresses must be upper case, in a format - * such as "00:11:22:33:AA:BB". The helper {@link #checkBluetoothAddress} is + *

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. *

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. + *

+ * 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 - * - *

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. + *

+ * 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). - * - *

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). + *

+ * 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}. + *

+ * 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 */ -- cgit v1.2.3 From be3185b409aeacb05e9f4a8b59d56e7805075ad5 Mon Sep 17 00:00:00 2001 From: Rahul Sabnis Date: Mon, 6 Jun 2022 13:54:07 -0700 Subject: Update API docs to state that the IRK must be supplied in little endian byte order Tag: #feature Bug: 233217148 Test: Manual (docs change) Ignore-AOSP-First: Android T docs change Change-Id: I5cab17003c22329744341235bb053cb55b4f7989 --- framework/java/android/bluetooth/le/ScanFilter.java | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) (limited to 'framework/java') diff --git a/framework/java/android/bluetooth/le/ScanFilter.java b/framework/java/android/bluetooth/le/ScanFilter.java index ee65f168be..bf902e889a 100644 --- a/framework/java/android/bluetooth/le/ScanFilter.java +++ b/framework/java/android/bluetooth/le/ScanFilter.java @@ -742,11 +742,11 @@ public final class ScanFilter implements Parcelable { * address can be validated using {@link BluetoothAdapter#checkBluetoothAddress}. *

* The IRK is used to resolve a static address from a private address. The IRK must be - * provided in big endian byte order. + * provided in little endian byte order. * * @param deviceAddress the remote device Bluetooth address for the filter * @param addressType indication of the type of address - * @param irk non-null byte array representing the Identity Resolving Key + * @param irk non-null little endian byte array representing the Identity Resolving Key * * @throws IllegalArgumentException If the {@code deviceAddress} is invalid * @throws IllegalArgumentException if the {@code irk} is invalid length @@ -777,9 +777,8 @@ public final class ScanFilter implements Parcelable { * format of "01:02:03:AB:CD:EF". The device address can be validated using {@link * BluetoothAdapter#checkBluetoothAddress}. * @param addressType indication of the type of address - * e.g. {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC} - * @param irk non-null byte array representing the Identity Resolving Address; nullable - * internally. + * @param irk non-null little endian byte array representing the Identity Resolving Key; + * nullable internally. * * @throws IllegalArgumentException if the {@code deviceAddress} is invalid * @throws IllegalArgumentException if the {@code addressType} is not PUBLIC or RANDOM -- cgit v1.2.3 From 87e5ce2d1145387388a14f053c7e9f28d4b929ae Mon Sep 17 00:00:00 2001 From: Etienne Ruffieux Date: Mon, 6 Jun 2022 17:34:43 -0700 Subject: Modify incorrect API documentation BluetoothAdapter#listenUsingInsecureRfcommWithServiceRecord description was stating user should call BluetoothDevice#createRfcommSocketToServiceRecord to connect, but user should use BluetoothDevice#createInsecureRfcommSocketToServiceRecord instead. Tag: #feature Test: build Bug: 235047894 Ignore-AOSP-First: cherry-pick Change-Id: I6469862134d398bba8e9c738eaba081dc3ee6d65 Merged-In: I770a00dd99abab967590d100607a8b1292dc0492 --- framework/java/android/bluetooth/BluetoothAdapter.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'framework/java') diff --git a/framework/java/android/bluetooth/BluetoothAdapter.java b/framework/java/android/bluetooth/BluetoothAdapter.java index e4bfc42b86..0fdadf85eb 100644 --- a/framework/java/android/bluetooth/BluetoothAdapter.java +++ b/framework/java/android/bluetooth/BluetoothAdapter.java @@ -3364,7 +3364,7 @@ public final class BluetoothAdapter { * can use the same UUID to query our SDP server and discover which channel * to connect to. This SDP record will be removed when this socket is * closed, or if this application closes unexpectedly. - *

Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to + *

Use {@link BluetoothDevice#createInsecureRfcommSocketToServiceRecord} to * connect to this socket from another device using the same {@link UUID}. * * @param name service name for SDP record -- cgit v1.2.3