docs for ESR: add docs to bluetooth explainin that discovery should

be cancelled before connecting to a device

bug: 2160782,2198463

3 files changed, 32 insertions, 6 deletions

diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index bd5b07cff640..bf561ef94ed4 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -130,13 +130,13 @@ public final class BluetoothAdapter {
 
     /**
      * 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 @@ public final class BluetoothAdapter {
      * {@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 @@ public final class BluetoothAdapter {
      * 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 @@ public final class BluetoothAdapter {
     /**
      * 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 1b23f6c048d2..c9c6c0acd9a7 100644
--- a/core/java/android/bluetooth/BluetoothServerSocket.java
+++ b/core/java/android/bluetooth/BluetoothServerSocket.java
@@ -42,7 +42,11 @@ import java.io.IOException;
  * 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 @@ public final class BluetoothServerSocket implements Closeable {
      * 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 dbcc758574b6..ad033999e0d2 100644
--- a/core/java/android/bluetooth/BluetoothSocket.java
+++ b/core/java/android/bluetooth/BluetoothSocket.java
@@ -180,6 +180,15 @@ public final class BluetoothSocket implements Closeable {
      * <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
      */