From 9fab0aef19a4633d2e4670564e5d7ae9e52fe11f Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 3 Nov 2009 18:17:59 -0800 Subject: [PATCH] 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. --- .../android/bluetooth/BluetoothAdapter.java | 29 ++++- .../android/bluetooth/BluetoothClass.java | 52 +++++--- .../android/bluetooth/BluetoothDevice.java | 23 +++- .../bluetooth/BluetoothServerSocket.java | 38 +++--- .../android/bluetooth/BluetoothSocket.java | 44 ++++--- core/java/android/bluetooth/package.html | 112 ++++++++++++++++-- 6 files changed, 229 insertions(+), 69 deletions(-) diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java index ff48583a80305..595156f71c547 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. - * - *

Use {@link #getDefaultAdapter} to get the default local Bluetooth - * adapter. - * - *

Use the {@link BluetoothDevice} class for operations on remote Bluetooth + * 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. + * + *

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

Note: + * 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 6210380595afb..bc067130584ef 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. * - *

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

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

Every Bluetooth Class is composed of zero or more service classes, and + *

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

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

{@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)}

* *

Use {@link BluetoothDevice#getBluetoothClass} to retrieve the class for * a remote device. + * + * */ public final class BluetoothClass implements Parcelable { /** @@ -91,7 +103,7 @@ public final class BluetoothClass implements Parcelable { } /** - * Bluetooth service classes. + * Defines all service class constants. *

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

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

Each {@link BluetoothClass} encodes exactly one device class, with * major and minor components. *

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

See {@link BluetoothClass.Service} for service class constants. */ public static class Device { private static final int BITMASK = 0x1FFC; + /** + * Defines all major device class constants. + *

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

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 849e6c7b24641..6cb9770a61005 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. - * - *

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

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

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

Note: + * 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 605bdc11e1934..1b23f6c048d25 100644 --- a/core/java/android/bluetooth/BluetoothServerSocket.java +++ b/core/java/android/bluetooth/BluetoothServerSocket.java @@ -27,29 +27,31 @@ import java.io.IOException; *

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

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

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

Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create - * a new {@link BluetoothSocket} ready for an outgoing connection to a remote - * {@link BluetoothDevice}. + *

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

Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to - * create a listening {@link BluetoothServerSocket} ready for incoming - * connections to the local {@link BluetoothAdapter}. - * - *

{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread + *

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

All methods on a {@link BluetoothServerSocket} require - * {@link android.Manifest.permission#BLUETOOTH} + *

Note: + * Requires the {@link android.Manifest.permission#BLUETOOTH} permission. + * + * {@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 7e725903b3e02..dbcc758574b65 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; *

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

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

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

Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create - * a new {@link BluetoothSocket} ready for an outgoing connection to a remote - * {@link BluetoothDevice}. + *

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

Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to - * create a listening {@link BluetoothServerSocket} ready for incoming - * connections to the local {@link BluetoothAdapter}. + *

To create a {@link BluetoothSocket} as a server (or "host"), see the + * {@link BluetoothServerSocket} documentation. * - *

{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread + *

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

{@link BluetoothSocket} is thread * safe. In particular, {@link #close} will always immediately abort ongoing * operations and close the socket. * - *

All methods on a {@link BluetoothSocket} require - * {@link android.Manifest.permission#BLUETOOTH} + *

Note: + * 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 79abf0cb4a046..4f0755e715083 100644 --- a/core/java/android/bluetooth/package.html +++ b/core/java/android/bluetooth/package.html @@ -1,13 +1,109 @@ -Provides classes that manage Bluetooth functionality on the device. -

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

The Bluetooth APIs let applications:

+ + +

Note: +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.

-

Remember, not all Android devices are guaranteed to have Bluetooth functionality.

+ +

Overview

+ +

Here's a basic introduction to the Bluetooth classes:

+
+
{@link android.bluetooth.BluetoothAdapter}
+
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.
+ +
{@link android.bluetooth.BluetoothDevice}
+
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.
+ +
{@link android.bluetooth.BluetoothSocket}
+
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}.
+
{@link android.bluetooth.BluetoothServerSocket}
+ +
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.
+ +
{@link android.bluetooth.BluetoothClass}
+
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.
+
+ + +

Example Procedure

+ +

For example, here's an pseudo-code procedure for discovering and +connecting a remote device, and transfering data:

+ +
    +
  1. Register a {@link android.content.BroadcastReceiver} that accepts the + {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent.
    2. +
  2. Call {@link android.bluetooth.BluetoothAdapter#getDefaultAdapter} to + retrieve the Android system's local + {@link android.bluetooth.BluetoothAdapter}.
    3. +
  3. 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.
    4. +
  4. 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.
    5. +
  5. Call {@link android.bluetooth.BluetoothSocket#connect() + BluetoothSocket.connect()} to connect with the remote device.
    6. +
  6. 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.
    7. +
  7. Use {@link java.io.InputStream#read(byte[]) InputStream.read()} and + {@link java.io.OutputStream#write(byte[]) OutputStream.write()} to transfer + data.
    8. +
+ + + +

Note: +Not all Android devices are guaranteed to have Bluetooth functionality.