diff options
author | Scott Main <smain@google.com> | 2009-11-03 18:17:59 -0800 |
---|---|---|
committer | Scott Main <smain@google.com> | 2009-11-09 18:09:12 -0800 |
commit | 9fab0aef19a4633d2e4670564e5d7ae9e52fe11f (patch) | |
tree | d39ce12d4517db2e75d20322dec6c132d565023d | |
parent | 0e08055aa31c752732005fc48b09ee470a2c4822 (diff) | |
download | frameworks_base-9fab0aef19a4633d2e4670564e5d7ae9e52fe11f.zip frameworks_base-9fab0aef19a4633d2e4670564e5d7ae9e52fe11f.tar.gz frameworks_base-9fab0aef19a4633d2e4670564e5d7ae9e52fe11f.tar.bz2 |
docs: add more documentation for the bluetooth apis.
more descriptions for some of the classes and a new
overview and pseudo-code example for using BT APIs
in the package summary.
-rw-r--r-- | core/java/android/bluetooth/BluetoothAdapter.java | 27 | ||||
-rw-r--r-- | core/java/android/bluetooth/BluetoothClass.java | 52 | ||||
-rw-r--r-- | core/java/android/bluetooth/BluetoothDevice.java | 23 | ||||
-rw-r--r-- | core/java/android/bluetooth/BluetoothServerSocket.java | 38 | ||||
-rw-r--r-- | core/java/android/bluetooth/BluetoothSocket.java | 44 | ||||
-rw-r--r-- | core/java/android/bluetooth/package.html | 112 |
6 files changed, 228 insertions, 68 deletions
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java index ff48583..595156f 100644 --- a/core/java/android/bluetooth/BluetoothAdapter.java +++ b/core/java/android/bluetooth/BluetoothAdapter.java @@ -36,13 +36,30 @@ import java.util.Set; import java.util.UUID; /** - * Represents the local Bluetooth adapter. + * Represents the local device Bluetooth adapter. The {@link BluetoothAdapter} + * lets you perform fundamental Bluetooth tasks, such as initiate + * device discovery, query a list of bonded (paired) devices, + * instantiate a {@link BluetoothDevice} using a known MAC address, and create + * a {@link BluetoothServerSocket} to listen for connection requests from other + * devices. * - * <p>Use {@link #getDefaultAdapter} to get the default local Bluetooth - * adapter. + * <p>To get a {@link BluetoothAdapter} representing the local Bluetooth + * adapter, call the static {@link #getDefaultAdapter} method. + * Fundamentally, this is your starting point for all + * Bluetooth actions. Once you have the local adapter, you can get a set of + * {@link BluetoothDevice} objects representing all paired devices with + * {@link #getBondedDevices()}; start device discovery with + * {@link #startDiscovery()}; or create a {@link BluetoothServerSocket} to + * listen for incoming connection requests with + * {@link #listenUsingRfcommWithServiceRecord(String,UUID)}. * - * <p>Use the {@link BluetoothDevice} class for operations on remote Bluetooth - * devices. + * <p class="note"><strong>Note:</strong> + * Most methods require the {@link android.Manifest.permission#BLUETOOTH} + * permission and some also require the + * {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission. + * + * {@see BluetoothDevice} + * {@see BluetoothServerSocket} */ public final class BluetoothAdapter { private static final String TAG = "BluetoothAdapter"; diff --git a/core/java/android/bluetooth/BluetoothClass.java b/core/java/android/bluetooth/BluetoothClass.java index 6210380..bc06713 100644 --- a/core/java/android/bluetooth/BluetoothClass.java +++ b/core/java/android/bluetooth/BluetoothClass.java @@ -20,25 +20,37 @@ import android.os.Parcel; import android.os.Parcelable; /** - * Represents a Bluetooth class. + * Represents a Bluetooth class, which describes general characteristics + * and capabilities of a device. For example, a Bluetooth class will + * specify the general device type such as a phone, a computer, or + * headset, and whether it's capable of services such as audio or telephony. * - * <p>Bluetooth Class is a 32 bit field. The format of these bits is defined at - * http://www.bluetooth.org/Technical/AssignedNumbers/baseband.htm - * (login required). This class contains that 32 bit field, and provides - * constants and methods to determine which Service Class(es) and Device Class - * are encoded in that field. + * <p>The Bluetooth class is useful as a hint to roughly describe a device (for example to + * show an icon in the UI), but does not reliably describe which Bluetooth + * profiles or services are actually supported by a device. * - * <p>Every Bluetooth Class is composed of zero or more service classes, and + * <p>Every Bluetooth class is composed of zero or more service classes, and * exactly one device class. The device class is further broken down into major * and minor device class components. * - * <p>Class is useful as a hint to roughly describe a device (for example to - * show an icon in the UI), but does not reliably describe which Bluetooth - * profiles or services are actually supported by a device. Accurate service - * discovery is done through SDP requests. + * <p>{@link BluetoothClass} is useful as a hint to roughly describe a device + * (for example to show an icon in the UI), but does not reliably describe which + * Bluetooth profiles or services are actually supported by a device. Accurate + * service discovery is done through SDP requests, which are automatically + * performed when creating an RFCOMM socket with {@link + * BluetoothDevice#createRfcommSocketToServiceRecord(UUID)} and {@link + * BluetoothAdapter#listenUsingRfcommWithServiceRecord(String,UUID)}</p> * * <p>Use {@link BluetoothDevice#getBluetoothClass} to retrieve the class for * a remote device. + * + * <!-- + * The Bluetooth class is a 32 bit field. The format of these bits is defined at + * http://www.bluetooth.org/Technical/AssignedNumbers/baseband.htm + * (login required). This class contains that 32 bit field, and provides + * constants and methods to determine which Service Class(es) and Device Class + * are encoded in that field. + * --> */ public final class BluetoothClass implements Parcelable { /** @@ -91,7 +103,7 @@ public final class BluetoothClass implements Parcelable { } /** - * Bluetooth service classes. + * Defines all service class constants. * <p>Each {@link BluetoothClass} encodes zero or more service classes. */ public static final class Service { @@ -109,7 +121,8 @@ public final class BluetoothClass implements Parcelable { } /** - * Return true if the specified service class is supported by this class. + * Return true if the specified service class is supported by this + * {@link BluetoothClass}. * <p>Valid service classes are the public constants in * {@link BluetoothClass.Service}. For example, {@link * BluetoothClass.Service#AUDIO}. @@ -122,17 +135,22 @@ public final class BluetoothClass implements Parcelable { } /** - * Bluetooth device classes. + * Defines all device class constants. * <p>Each {@link BluetoothClass} encodes exactly one device class, with * major and minor components. * <p>The constants in {@link * BluetoothClass.Device} represent a combination of major and minor - * components (the complete device class). The constants in {@link - * BluetoothClass.Device.Major} represent just the major device classes. + * device components (the complete device class). The constants in {@link + * BluetoothClass.Device.Major} represent only major device classes. + * <p>See {@link BluetoothClass.Service} for service class constants. */ public static class Device { private static final int BITMASK = 0x1FFC; + /** + * Defines all major device class constants. + * <p>See {@link BluetoothClass.Device} for minor classes. + */ public static class Major { private static final int BITMASK = 0x1F00; @@ -215,7 +233,7 @@ public final class BluetoothClass implements Parcelable { } /** - * Return the major device class component of this Bluetooth class. + * Return the major device class component of this {@link BluetoothClass}. * <p>Values returned from this function can be compared with the * public constants in {@link BluetoothClass.Device.Major} to determine * which major class is encoded in this Bluetooth class. diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java index 849e6c7..6cb9770 100644 --- a/core/java/android/bluetooth/BluetoothDevice.java +++ b/core/java/android/bluetooth/BluetoothDevice.java @@ -31,16 +31,31 @@ import java.io.UnsupportedEncodingException; import java.util.UUID; /** - * Represents a remote Bluetooth device. - * - * <p>Use {@link BluetoothAdapter#getRemoteDevice} to create a {@link - * BluetoothDevice}. + * Represents a remote Bluetooth device. A {@link BluetoothDevice} lets you + * create a connection with the repective device or query information about + * it, such as the name, address, class, and bonding state. * * <p>This class is really just a thin wrapper for a Bluetooth hardware * address. Objects of this class are immutable. Operations on this class * are performed on the remote Bluetooth hardware address, using the * {@link BluetoothAdapter} that was used to create this {@link * BluetoothDevice}. + * + * <p>To get a {@link BluetoothDevice}, use + * {@link BluetoothAdapter#getRemoteDevice(String) + * BluetoothAdapter.getRemoteDevice(String)} to create one representing a device + * of a known MAC address (which you can get through device discovery with + * {@link BluetoothAdapter}) or get one from the set of bonded devices + * returned by {@link BluetoothAdapter#getBondedDevices() + * BluetoothAdapter.getBondedDevices()}. You can then open a + * {@link BluetoothSocket} for communciation with the remote device, using + * {@link #createRfcommSocketToServiceRecord(UUID)}. + * + * <p class="note"><strong>Note:</strong> + * Requires the {@link android.Manifest.permission#BLUETOOTH} permission. + * + * {@see BluetoothAdapter} + * {@see BluetoothSocket} */ public final class BluetoothDevice implements Parcelable { private static final String TAG = "BluetoothDevice"; diff --git a/core/java/android/bluetooth/BluetoothServerSocket.java b/core/java/android/bluetooth/BluetoothServerSocket.java index 605bdc1..1b23f6c 100644 --- a/core/java/android/bluetooth/BluetoothServerSocket.java +++ b/core/java/android/bluetooth/BluetoothServerSocket.java @@ -27,29 +27,31 @@ import java.io.IOException; * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets: * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server * side, use a {@link BluetoothServerSocket} to create a listening server - * socket. It will return a new, connected {@link BluetoothSocket} on an - * accepted connection. On the client side, use the same - * {@link BluetoothSocket} object to both intiate the outgoing connection, - * and to manage the connected socket. + * socket. When a connection is accepted by the {@link BluetoothServerSocket}, + * it will return a new {@link BluetoothSocket} to manage the connection. + * On the client side, use a single {@link BluetoothSocket} to both intiate + * an outgoing connection and to manage the connection. * - * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a - * connection orientated, streaming transport over Bluetooth. It is also known - * as the Serial Port Profile (SPP). + * <p>The most common type of Bluetooth socket is RFCOMM, which is the type + * supported by the Android APIs. RFCOMM is a connection-oriented, streaming + * transport over Bluetooth. It is also known as the Serial Port Profile (SPP). * - * <p>Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create - * a new {@link BluetoothSocket} ready for an outgoing connection to a remote - * {@link BluetoothDevice}. + * <p>To create a listenting {@link BluetoothServerSocket} that's ready for + * incoming connections, use + * {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord + * 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. * - * <p>Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to - * create a listening {@link BluetoothServerSocket} ready for incoming - * connections to the local {@link BluetoothAdapter}. - * - * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread + * <p>{@link BluetoothServerSocket} is thread * safe. In particular, {@link #close} will always immediately abort ongoing - * operations and close the socket. + * operations and close the server socket. + * + * <p class="note"><strong>Note:</strong> + * Requires the {@link android.Manifest.permission#BLUETOOTH} permission. * - * <p>All methods on a {@link BluetoothServerSocket} require - * {@link android.Manifest.permission#BLUETOOTH} + * {@see BluetoothSocket} */ public final class BluetoothServerSocket implements Closeable { diff --git a/core/java/android/bluetooth/BluetoothSocket.java b/core/java/android/bluetooth/BluetoothSocket.java index 7e72590..dbcc758 100644 --- a/core/java/android/bluetooth/BluetoothSocket.java +++ b/core/java/android/bluetooth/BluetoothSocket.java @@ -33,29 +33,41 @@ import java.util.concurrent.locks.ReentrantReadWriteLock; * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets: * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server * side, use a {@link BluetoothServerSocket} to create a listening server - * socket. It will return a new, connected {@link BluetoothSocket} on an - * accepted connection. On the client side, use the same - * {@link BluetoothSocket} object to both intiate the outgoing connection, - * and to manage the connected socket. + * socket. When a connection is accepted by the {@link BluetoothServerSocket}, + * it will return a new {@link BluetoothSocket} to manage the connection. + * On the client side, use a single {@link BluetoothSocket} to both intiate + * an outgoing connection and to manage the connection. * - * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a - * connection orientated, streaming transport over Bluetooth. It is also known - * as the Serial Port Profile (SPP). + * <p>The most common type of Bluetooth socket is RFCOMM, which is the type + * supported by the Android APIs. RFCOMM is a connection-oriented, streaming + * transport over Bluetooth. It is also known as the Serial Port Profile (SPP). * - * <p>Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create - * a new {@link BluetoothSocket} ready for an outgoing connection to a remote - * {@link BluetoothDevice}. + * <p>To create a {@link BluetoothSocket} for connecting to a known device, use + * {@link BluetoothDevice#createRfcommSocketToServiceRecord + * BluetoothDevice.createRfcommSocketToServiceRecord()}. + * Then call {@link #connect()} to attempt a connection to the remote device. + * This call will block until a connection is established or the connection + * fails. * - * <p>Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to - * create a listening {@link BluetoothServerSocket} ready for incoming - * connections to the local {@link BluetoothAdapter}. + * <p>To create a {@link BluetoothSocket} as a server (or "host"), see the + * {@link BluetoothServerSocket} documentation. * - * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread + * <p>Once the socket is connected, whether initiated as a client or accepted + * as a server, open the IO streams by calling {@link #getInputStream} and + * {@link #getOutputStream} in order to retrieve {@link java.io.InputStream} + * and {@link java.io.OutputStream} objects, respectively, which are + * automatically connected to the socket. + * + * <p>{@link BluetoothSocket} is thread * safe. In particular, {@link #close} will always immediately abort ongoing * operations and close the socket. * - * <p>All methods on a {@link BluetoothSocket} require - * {@link android.Manifest.permission#BLUETOOTH} + * <p class="note"><strong>Note:</strong> + * Requires the {@link android.Manifest.permission#BLUETOOTH} permission. + * + * {@see BluetoothServerSocket} + * {@see java.io.InputStream} + * {@see java.io.OutputStream} */ public final class BluetoothSocket implements Closeable { private static final String TAG = "BluetoothSocket"; diff --git a/core/java/android/bluetooth/package.html b/core/java/android/bluetooth/package.html index 79abf0c..4f0755e 100644 --- a/core/java/android/bluetooth/package.html +++ b/core/java/android/bluetooth/package.html @@ -1,13 +1,109 @@ <HTML> <BODY> -Provides classes that manage Bluetooth functionality on the device. -<p> -The Bluetooth APIs allow applications can connect and disconnect headsets, or scan -for other kinds of Bluetooth devices and pair them. Further control includes the -ability to write and modify the local Service Discovery Protocol (SDP) database, -query the SDP database of other Bluetooth devices, establish RFCOMM -channels/sockets on Android, and connect to specified sockets on other devices. +Provides classes that manage Bluetooth functionality, such as scanning for +devices, connecting with devices, and managing data transfer between devices. + +<p>The Bluetooth APIs let applications:</p> +<ul> + <li>Scan for other Bluetooth devices</li> + <li>Query the local Bluetooth adapter for paired Bluetooth devices</li> + <li>Establish RFCOMM channels/sockets</li> + <li>Connect to specified sockets on other devices</li> + <li>Transfer data to and from other devices</li> +</ul> + +<p class="note"><strong>Note:</strong> +To perform Bluetooth communication using these APIs, an application must +declare the {@link android.Manifest.permission#BLUETOOTH} permission. Some +additional functionality, such as requesting device discovery and +pairing also requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN} +permission. </p> -<p>Remember, not all Android devices are guaranteed to have Bluetooth functionality.</p> + +<h3>Overview</h3> + +<p>Here's a basic introduction to the Bluetooth classes:</p> +<dl> + <dt>{@link android.bluetooth.BluetoothAdapter}</dt> + <dd>This represents the local Bluetooth adapter, which is essentially the + entry-point to performing any interaction with Bluetooth. With it, you can + discover other Bluetooth devices, query a list of bonded (paired) devices, + initialize a {@link android.bluetooth.BluetoothDevice} using a known MAC + address, and create a {@link android.bluetooth.BluetoothServerSocket} to + listen for communications from other devices.</dd> + + <dt>{@link android.bluetooth.BluetoothDevice}</dt> + <dd>This represents a remote Bluetooth device. Use this to request a + connection with a remote device through a + {@link android.bluetooth.BluetoothSocket} + or query information about the device such as its name, address, class, and + bonding state.</dd> + + <dt>{@link android.bluetooth.BluetoothSocket}</dt> + <dd>This represents the interface for a Bluetooth socket + (similar to a TCP client-side {@link java.net.Socket}). This is the + connection point that allows an app to transfer data with another Bluetooth + device via {@link java.io.InputStream} and {@link java.io.OutputStream}.</dd> + <dt>{@link android.bluetooth.BluetoothServerSocket}</dt> + + <dd>This represents an open server socket that listens for incoming requests + (similar to a TCP server-side {@link java.net.ServerSocket}). + When attempting to connect two Android devices, one device will need to open + a server socket with this class. When a connection is accepted, a new + {@link android.bluetooth.BluetoothSocket} will be returned, + which can be used to manage the connection and transfer data.</dd> + + <dt>{@link android.bluetooth.BluetoothClass}</dt> + <dd>This represents the Bluetooth class for a device which describes general + characteristics and capabilities of a device. This class and its subclasses + don't provide any actual functionality. The sub-classes are entirely composed + of constants for the device and service class definitions.</dd> +</dl> + + +<h3>Example Procedure</h3> + +<p>For example, here's an pseudo-code procedure for discovering and +connecting a remote device, and transfering data:</p> + +<ol> + <li>Register a {@link android.content.BroadcastReceiver} that accepts the + {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent.</li> + <li>Call {@link android.bluetooth.BluetoothAdapter#getDefaultAdapter} to + retrieve the Android system's local + {@link android.bluetooth.BluetoothAdapter}.</li> + <li>Call {@link android.bluetooth.BluetoothAdapter#startDiscovery() + BluetoothAdapter.startDiscovery()} to scan for local devices. This is where + the BroadcastReceiver comes in; Android now scans for devices and will + broadcast the {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent + for each remote device discovered. The + {@link android.content.BroadcastReceiver} + you created will receive each Intent.</li> + <li>The {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent + includes the {@link android.bluetooth.BluetoothDevice#EXTRA_DEVICE} + Parcelable extra, which is a {@link android.bluetooth.BluetoothDevice} + object. Extract this from the Intent and call + {@link android.bluetooth.BluetoothDevice#createRfcommSocketToServiceRecord(java.util.UUID) + BluetoothDevice.createRfcommSocketToServiceRecord()} + to open a {@link android.bluetooth.BluetoothSocket} with a chosen + remote device.</li> + <li>Call {@link android.bluetooth.BluetoothSocket#connect() + BluetoothSocket.connect()} to connect with the remote device.</li> + <li>When successfully connected, call + {@link android.bluetooth.BluetoothSocket#getInputStream() + BluetoothSocket.getInputStream()} and/or + {@link android.bluetooth.BluetoothSocket#getOutputStream() + BluetoothSocket.getOutputStream()} to retreive an + {@link java.io.InputStream} and {@link java.io.OutputStream}, respectively, + which are hooked into the socket.</li> + <li>Use {@link java.io.InputStream#read(byte[]) InputStream.read()} and + {@link java.io.OutputStream#write(byte[]) OutputStream.write()} to transfer + data.</li> +</ol> + + + +<p class="note"><strong>Note:</strong> +Not all Android devices are guaranteed to have Bluetooth functionality.</p> </BODY> </HTML> |