docs for ESR: add docs to bluetooth explainin that discovery should
be cancelled before connecting to a device
bug: 2160782,2198463
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index bd5b07c..bf561ef 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -130,13 +130,13 @@
/**
* Activity Action: Show a system activity that requests discoverable mode.
- * <p>This activity will also request the user to turn on Bluetooth if it
+ * This activity will also request the user to turn on Bluetooth if it
* is not currently enabled.
* <p>Discoverable mode is equivalent to {@link
* #SCAN_MODE_CONNECTABLE_DISCOVERABLE}. It allows remote devices to see
* this Bluetooth adapter when they perform a discovery.
- * <p>For privacy, Android is not by default discoverable.
- * <p>The sender can optionally use extra field {@link
+ * <p>For privacy, Android is not discoverable by default.
+ * <p>The sender of this Intent can optionally use extra field {@link
* #EXTRA_DISCOVERABLE_DURATION} to request the duration of
* discoverability. Currently the default duration is 120 seconds, and
* maximum duration is capped at 300 seconds for each request.
@@ -147,7 +147,8 @@
* {@link android.app.Activity#RESULT_CANCELED} if the user rejected
* discoverability or an error has occurred.
* <p>Applications can also listen for {@link #ACTION_SCAN_MODE_CHANGED}
- * for global notification whenever the scan mode changes.
+ * for global notification whenever the scan mode changes. For example, an
+ * application can be notified when the device has ended discoverability.
* <p>Requires {@link android.Manifest.permission#BLUETOOTH}
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
@@ -549,7 +550,10 @@
* remote Bluetooth devices should not be attempted while discovery is in
* progress, and existing connections will experience limited bandwidth
* and high latency. Use {@link #cancelDiscovery()} to cancel an ongoing
- * discovery.
+ * discovery. Discovery is not managed by the Activity,
+ * but is run as a system service, so an application should always call
+ * {@link BluetoothAdapter#cancelDiscovery()} even if it
+ * did not directly request a discovery, just to be sure.
* <p>Device discovery will only find remote devices that are currently
* <i>discoverable</i> (inquiry scan enabled). Many Bluetooth devices are
* not discoverable by default, and need to be entered into a special mode.
@@ -567,6 +571,13 @@
/**
* Cancel the current device discovery process.
* <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
+ * <p>Because discovery is a heavyweight precedure for the Bluetooth
+ * adapter, this method should always be called before attempting to connect
+ * to a remote device with {@link
+ * android.bluetooth.BluetoothSocket#connect()}. Discovery is not managed by
+ * the Activity, but is run as a system service, so an application should
+ * always call cancel discovery even if it did not directly request a
+ * discovery, just to be sure.
*
* @return true on success, false on error
*/
diff --git a/core/java/android/bluetooth/BluetoothServerSocket.java b/core/java/android/bluetooth/BluetoothServerSocket.java
index 1b23f6c..c9c6c0a 100644
--- a/core/java/android/bluetooth/BluetoothServerSocket.java
+++ b/core/java/android/bluetooth/BluetoothServerSocket.java
@@ -42,7 +42,11 @@
* BluetoothAdapter.listenUsingRfcommWithServiceRecord()}. Then call
* {@link #accept()} to listen for incoming connection requests. This call
* will block until a connection is established, at which point, it will return
- * a {@link BluetoothSocket} to manage the connection.
+ * a {@link BluetoothSocket} to manage the connection. Once the {@link
+ * BluetoothSocket} is acquired, it's a good idea to call {@link #close()} on
+ * the {@link BluetoothServerSocket} when it's no longer needed for accepting
+ * connections. Closing the {@link BluetoothServerSocket} will <em>not</em>
+ * close the returned {@link BluetoothSocket}.
*
* <p>{@link BluetoothServerSocket} is thread
* safe. In particular, {@link #close} will always immediately abort ongoing
@@ -105,6 +109,8 @@
* Immediately close this socket, and release all associated resources.
* <p>Causes blocked calls on this socket in other threads to immediately
* throw an IOException.
+ * <p>Closing the {@link BluetoothServerSocket} will <em>not</em>
+ * close any {@link BluetoothSocket} received from {@link #accept()}.
*/
public void close() throws IOException {
synchronized (this) {
diff --git a/core/java/android/bluetooth/BluetoothSocket.java b/core/java/android/bluetooth/BluetoothSocket.java
index dbcc758..ad03399 100644
--- a/core/java/android/bluetooth/BluetoothSocket.java
+++ b/core/java/android/bluetooth/BluetoothSocket.java
@@ -180,6 +180,15 @@
* <p>This method will block until a connection is made or the connection
* fails. If this method returns without an exception then this socket
* is now connected.
+ * <p>Creating new connections to
+ * remote Bluetooth devices should not be attempted while device discovery
+ * is in progress. Device discovery is a heavyweight procedure on the
+ * Bluetooth adapter and will significantly slow a device connection.
+ * Use {@link BluetoothAdapter#cancelDiscovery()} to cancel an ongoing
+ * discovery. Discovery is not managed by the Activity,
+ * but is run as a system service, so an application should always call
+ * {@link BluetoothAdapter#cancelDiscovery()} even if it
+ * did not directly request a discovery, just to be sure.
* <p>{@link #close} can be used to abort this call from another thread.
* @throws IOException on error, for example connection failure
*/
