am 6d95fc0a: docs for ESR: add docs to bluetooth explainin that discovery... (e1611399) · Commits · e / os / android_frameworks_base

core/java/android/bluetooth/BluetoothAdapter.java

+16 −5

Original line number	Diff line number	Diff line
		@@ -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
		*/

core/java/android/bluetooth/BluetoothServerSocket.java

+7 −1

Original line number	Diff line number	Diff line
		@@ -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) {

core/java/android/bluetooth/BluetoothSocket.java

+9 −0

Original line number	Diff line number	Diff line
		@@ -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
		*/