API CHANGE

Javadoc, and unhide the first pieces of the Bluetooth API.

With this commit there is enough public API to connect and use an RFCOMM
connection between Bluetooth devices.

6 files changed, 457 insertions, 85 deletions

diff --git a/api/current.xml b/api/current.xml
index e9c3b30..881c71f 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -25001,6 +25001,235 @@
 </field>
 </class>
 </package>
+<package name="android.bluetooth"
+>
+<class name="BluetoothAdapter"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<method name="getRemoteDevice"
+ return="android.bluetooth.BluetoothDevice"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="address" type="java.lang.String">
+</parameter>
+</method>
+<method name="listenUsingRfcommOn"
+ return="android.bluetooth.BluetoothServerSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="channel" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+</class>
+<class name="BluetoothDevice"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="android.os.Parcelable">
+</implements>
+<method name="createRfcommSocket"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="channel" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="describeContents"
+ return="int"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="getAddress"
+ return="java.lang.String"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="writeToParcel"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="out" type="android.os.Parcel">
+</parameter>
+<parameter name="flags" type="int">
+</parameter>
+</method>
+</class>
+<class name="BluetoothServerSocket"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="java.io.Closeable">
+</implements>
+<method name="accept"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="accept"
+ return="android.bluetooth.BluetoothSocket"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="timeout" type="int">
+</parameter>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="close"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+</class>
+<class name="BluetoothSocket"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<implements name="java.io.Closeable">
+</implements>
+<method name="close"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="connect"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getInputStream"
+ return="java.io.InputStream"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getOutputStream"
+ return="java.io.OutputStream"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<exception name="IOException" type="java.io.IOException">
+</exception>
+</method>
+<method name="getRemoteDevice"
+ return="android.bluetooth.BluetoothDevice"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+</class>
+</package>
 <package name="android.content"
 >
 <class name="AbstractCursorEntityIterator"
@@ -29359,6 +29588,17 @@
  visibility="public"
 >
 </field>
+<field name="BLUETOOTH_SERVICE"
+ type="java.lang.String"
+ transient="false"
+ volatile="false"
+ value="&quot;bluetooth&quot;"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 <field name="CLIPBOARD_SERVICE"
  type="java.lang.String"
  transient="false"
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index d207540..6bd2a5a 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -27,34 +27,54 @@ import java.util.HashSet;
 /**
  * Represents the local Bluetooth adapter.
  *
- * @hide
+ * <p>Use {@link android.content.Context#getSystemService} with {@link
+ * android.content.Context#BLUETOOTH_SERVICE} to get the default local
+ * Bluetooth adapter. On most Android devices there is only one local
+ * Bluetotoh adapter.
+ *
+ * <p>Use the {@link BluetoothDevice} class for operations on remote Bluetooth
+ * devices.
+ *
+ * <p>TODO: unhide more of this class
  */
 public final class BluetoothAdapter {
     private static final String TAG = "BluetoothAdapter";
 
+    /** @hide */
     public static final int BLUETOOTH_STATE_OFF = 0;
+    /** @hide */
     public static final int BLUETOOTH_STATE_TURNING_ON = 1;
+    /** @hide */
     public static final int BLUETOOTH_STATE_ON = 2;
+    /** @hide */
     public static final int BLUETOOTH_STATE_TURNING_OFF = 3;
 
     /** Inquiry scan and page scan are both off.
-     *  Device is neither discoverable nor connectable */
+     *  Device is neither discoverable nor connectable
+     *  @hide */
     public static final int SCAN_MODE_NONE = 0;
     /** Page scan is on, inquiry scan is off.
-     *  Device is connectable, but not discoverable */
+     *  Device is connectable, but not discoverable
+     *  @hide*/
     public static final int SCAN_MODE_CONNECTABLE = 1;
     /** Page scan and inquiry scan are on.
-     *  Device is connectable and discoverable */
+     *  Device is connectable and discoverable
+     *  @hide*/
     public static final int SCAN_MODE_CONNECTABLE_DISCOVERABLE = 3;
 
+    /** @hide */
     public static final int RESULT_FAILURE = -1;
+    /** @hide */
     public static final int RESULT_SUCCESS = 0;
 
-    /* The user will be prompted to enter a pin */
+    /** The user will be prompted to enter a pin
+     * @hide */
     public static final int PAIRING_VARIANT_PIN = 0;
-    /* The user will be prompted to enter a passkey */
+    /** The user will be prompted to enter a passkey
+     * @hide */
     public static final int PAIRING_VARIANT_PASSKEY = 1;
-    /* The user will be prompted to confirm the passkey displayed on the screen */
+    /** The user will be prompted to confirm the passkey displayed on the screen
+     * @hide */
     public static final int PAIRING_VARIANT_CONFIRMATION = 2;
 
     private final IBluetooth mService;
@@ -71,9 +91,14 @@ public final class BluetoothAdapter {
     }
 
     /**
-     * Get the remote BluetoothDevice associated with the given MAC address.
-     * Bluetooth MAC address must be upper case, such as "00:11:22:33:AA:BB".
+     * Get a {@link BluetoothDevice} object for the given Bluetooth hardware
+     * address.
+     * <p>Valid Bluetooth hardware addresses must be upper case, in a format
+     * such as "00:11:22:33:AA:BB".
+     * <p>A {@link BluetoothDevice} will always be returned for a valid
+     * hardware address, even if this adapter has never seen that device.
      * @param address valid Bluetooth MAC address
+     * @throws IllegalArgumentException if address is invalid
      */
     public BluetoothDevice getRemoteDevice(String address) {
         return new BluetoothDevice(address);
@@ -83,6 +108,7 @@ public final class BluetoothAdapter {
      * Is Bluetooth currently turned on.
      *
      * @return true if Bluetooth enabled, false otherwise.
+     * @hide
      */
     public boolean isEnabled() {
         try {
@@ -95,6 +121,7 @@ public final class BluetoothAdapter {
      * Get the current state of Bluetooth.
      *
      * @return One of BLUETOOTH_STATE_ or BluetoothError.ERROR.
+     * @hide
      */
     public int getBluetoothState() {
         try {
@@ -112,6 +139,7 @@ public final class BluetoothAdapter {
      * @return false if we cannot enable the Bluetooth device. True does not
      * imply the device was enabled, it only implies that so far there were no
      * problems.
+     * @hide
      */
     public boolean enable() {
         try {
@@ -125,6 +153,7 @@ public final class BluetoothAdapter {
      * This turns off the underlying hardware.
      *
      * @return true if successful, false otherwise.
+     * @hide
      */
     public boolean disable() {
         try {
@@ -133,6 +162,7 @@ public final class BluetoothAdapter {
         return false;
     }
 
+    /** @hide */
     public String getAddress() {
         try {
             return mService.getAddress();
@@ -147,6 +177,7 @@ public final class BluetoothAdapter {
      * possible to retrieve the Bluetooth name when Bluetooth is enabled.
      *
      * @return the Bluetooth name, or null if there was a problem.
+     * @hide
      */
     public String getName() {
         try {
@@ -163,6 +194,7 @@ public final class BluetoothAdapter {
      *
      * @param name the name to set
      * @return     true, if the name was successfully set. False otherwise.
+     * @hide
      */
     public boolean setName(String name) {
         try {
@@ -175,6 +207,7 @@ public final class BluetoothAdapter {
      * Get the current scan mode.
      * Used to determine if the local device is connectable and/or discoverable
      * @return Scan mode, one of SCAN_MODE_* or an error code
+     * @hide
      */
     public int getScanMode() {
         try {
@@ -187,6 +220,7 @@ public final class BluetoothAdapter {
      * Set the current scan mode.
      * Used to make the local device connectable and/or discoverable
      * @param scanMode One of SCAN_MODE_*
+     * @hide
      */
     public void setScanMode(int scanMode) {
         try {
@@ -194,6 +228,7 @@ public final class BluetoothAdapter {
         } catch (RemoteException e) {Log.e(TAG, "", e);}
     }
 
+    /** @hide */
     public int getDiscoverableTimeout() {
         try {
             return mService.getDiscoverableTimeout();
@@ -201,12 +236,14 @@ public final class BluetoothAdapter {
         return -1;
     }
 
+    /** @hide */
     public void setDiscoverableTimeout(int timeout) {
         try {
             mService.setDiscoverableTimeout(timeout);
         } catch (RemoteException e) {Log.e(TAG, "", e);}
     }
 
+    /** @hide */
     public boolean startDiscovery() {
         try {
             return mService.startDiscovery();
@@ -214,12 +251,14 @@ public final class BluetoothAdapter {
         return false;
     }
 
+    /** @hide */
     public void cancelDiscovery() {
         try {
             mService.cancelDiscovery();
         } catch (RemoteException e) {Log.e(TAG, "", e);}
     }
 
+    /** @hide */
     public boolean isDiscovering() {
         try {
             return mService.isDiscovering();
@@ -248,6 +287,7 @@ public final class BluetoothAdapter {
      * returned.
      *
      * @return unmodifiable set of bonded devices, or null on error
+     * @hide
      */
     public Set<BluetoothDevice> getBondedDevices() {
         try {
@@ -257,17 +297,20 @@ public final class BluetoothAdapter {
     }
 
     /**
-     * Construct a listening, secure RFCOMM server socket.
-     * The remote device connecting to this socket will be authenticated and
+     * Create a listening, secure RFCOMM Bluetooth socket.
+     * <p>A remote device connecting to this socket will be authenticated and
      * communication on this socket will be encrypted.
-     * Call #accept to retrieve connections to this socket.
-     * @return An RFCOMM BluetoothServerSocket
-     * @throws IOException On error, for example Bluetooth not available, or
-     *                     insufficient permissions.
+     * <p>Use {@link BluetoothServerSocket#accept} to retrieve incoming
+     * connections to listening {@link BluetoothServerSocket}.
+     * <p>Valid RFCOMM channels are in range 1 to 30.
+     * @param channel RFCOMM channel to listen on
+     * @return a listening RFCOMM BluetoothServerSocket
+     * @throws IOException on error, for example Bluetooth not available, or
+     *                     insufficient permissions, or channel in use.
      */
-    public BluetoothServerSocket listenUsingRfcommOn(int port) throws IOException {
+    public BluetoothServerSocket listenUsingRfcommOn(int channel) throws IOException {
         BluetoothServerSocket socket = new BluetoothServerSocket(
-                BluetoothSocket.TYPE_RFCOMM, true, true, port);
+                BluetoothSocket.TYPE_RFCOMM, true, true, channel);
         try {
             socket.mSocket.bindListenNative();
         } catch (IOException e) {
@@ -285,6 +328,7 @@ public final class BluetoothAdapter {
      * @return An RFCOMM BluetoothServerSocket
      * @throws IOException On error, for example Bluetooth not available, or
      *                     insufficient permissions.
+     * @hide
      */
     public BluetoothServerSocket listenUsingInsecureRfcommOn(int port) throws IOException {
         BluetoothServerSocket socket = new BluetoothServerSocket(
@@ -306,6 +350,7 @@ public final class BluetoothAdapter {
      * @return A SCO BluetoothServerSocket
      * @throws IOException On error, for example Bluetooth not available, or
      *                     insufficient permissions.
+     * @hide
      */
     public static BluetoothServerSocket listenUsingScoOn() throws IOException {
         BluetoothServerSocket socket = new BluetoothServerSocket(
diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java
index 27b2849..1a97924 100644
--- a/core/java/android/bluetooth/BluetoothDevice.java
+++ b/core/java/android/bluetooth/BluetoothDevice.java
@@ -30,41 +30,62 @@ import java.io.UnsupportedEncodingException;
 /**
  * Represents a remote Bluetooth device.
  *
- * TODO: unhide
- * @hide
+ * <p>Use {@link BluetoothAdapter#getRemoteDevice} to create a {@link
+ * BluetoothDevice}.
+ *
+ * <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}.
+ *
+ * TODO: unhide more of this class
  */
 public final class BluetoothDevice implements Parcelable {
     private static final String TAG = "BluetoothDevice";
 
     /** We do not have a link key for the remote device, and are therefore not
-     * bonded */
+     * bonded
+     * @hide*/
     public static final int BOND_NOT_BONDED = 0;
-    /** We have a link key for the remote device, and are probably bonded. */
+    /** We have a link key for the remote device, and are probably bonded.
+     *  @hide */
     public static final int BOND_BONDED = 1;
-    /** We are currently attempting bonding */
+    /** We are currently attempting bonding
+     *  @hide */
     public static final int BOND_BONDING = 2;
 
     //TODO: Unify these result codes in BluetoothResult or BluetoothError
     /** A bond attempt failed because pins did not match, or remote device did
-     * not respond to pin request in time */
+     * not respond to pin request in time 
+     * @hide */
     public static final int UNBOND_REASON_AUTH_FAILED = 1;
     /** A bond attempt failed because the other side explicilty rejected
-     * bonding */
+     * bonding
+     * @hide */
     public static final int UNBOND_REASON_AUTH_REJECTED = 2;
-    /** A bond attempt failed because we canceled the bonding process */
+    /** A bond attempt failed because we canceled the bonding process
+     * @hide */
     public static final int UNBOND_REASON_AUTH_CANCELED = 3;
-    /** A bond attempt failed because we could not contact the remote device */
+    /** A bond attempt failed because we could not contact the remote device
+     * @hide */
     public static final int UNBOND_REASON_REMOTE_DEVICE_DOWN = 4;
-    /** A bond attempt failed because a discovery is in progress */
+    /** A bond attempt failed because a discovery is in progress
+     * @hide */
     public static final int UNBOND_REASON_DISCOVERY_IN_PROGRESS = 5;
-    /** An existing bond was explicitly revoked */
+    /** An existing bond was explicitly revoked
+     * @hide */
     public static final int UNBOND_REASON_REMOVED = 6;
 
-    /* The user will be prompted to enter a pin */
+    //TODO: Remove duplicates between here and BluetoothAdapter
+    /** The user will be prompted to enter a pin
+     * @hide */
     public static final int PAIRING_VARIANT_PIN = 0;
-    /* The user will be prompted to enter a passkey */
+    /** The user will be prompted to enter a passkey
+     * @hide */
     public static final int PAIRING_VARIANT_PASSKEY = 1;
-    /* The user will be prompted to confirm the passkey displayed on the screen */
+    /** The user will be prompted to confirm the passkey displayed on the screen
+     * @hide */
     public static final int PAIRING_VARIANT_CONFIRMATION = 2;
 
     private static final int ADDRESS_LENGTH = 17;
@@ -113,15 +134,25 @@ public final class BluetoothDevice implements Parcelable {
         return mAddress.hashCode();
     }
 
+    /**
+     * Returns a string representation of this BluetoothDevice.
+     * <p>Currently this is the Bluetooth hardware address, for example
+     * "00:11:22:AA:BB:CC". However, you should always use {@link #getAddress}
+     * if you explicitly require the Bluetooth hardware address in case the
+     * {@link #toString} representation changes in the future.
+     * @return string representation of this BluetoothDevice
+     */
     @Override
     public String toString() {
         return mAddress;
     }
 
+    /** @hide */
     public int describeContents() {
         return 0;
     }
 
+    /** @hide */
     public static final Parcelable.Creator<BluetoothDevice> CREATOR =
             new Parcelable.Creator<BluetoothDevice>() {
         public BluetoothDevice createFromParcel(Parcel in) {
@@ -132,21 +163,29 @@ public final class BluetoothDevice implements Parcelable {
         }
     };
 
+    /** @hide */
     public void writeToParcel(Parcel out, int flags) {
         out.writeString(mAddress);
     }
 
+    /**
+     * Returns the hardware address of this BluetoothDevice.
+     * <p> For example, "00:11:22:AA:BB:CC".
+     * @return Bluetooth hardware address as string
+     */
     public String getAddress() {
         return mAddress;
     }
 
     /**
-     * Get the friendly Bluetooth name of this remote device.
+     * Get the friendly Bluetooth name of the remote device.
      *
-     * This name is visible to remote Bluetooth devices. Currently it is only
-     * possible to retrieve the Bluetooth name when Bluetooth is enabled.
+     * <p>The local adapter will automatically retrieve remote names when
+     * performing a device scan, and will cache them. This method just returns
+     * the name for this device from the cache.
      *
      * @return the Bluetooth name, or null if there was a problem.
+     * @hide
      */
     public String getName() {
         try {
@@ -164,6 +203,7 @@ public final class BluetoothDevice implements Parcelable {
      * @param address the remote device Bluetooth address.
      * @return false If there was an immediate problem creating the bonding,
      *         true otherwise.
+     * @hide
      */
     public boolean createBond() {
         try {
@@ -174,6 +214,7 @@ public final class BluetoothDevice implements Parcelable {
 
     /**
      * Cancel an in-progress bonding request started with createBond.
+     * @hide
      */
     public boolean cancelBondProcess() {
         try {
@@ -188,6 +229,7 @@ public final class BluetoothDevice implements Parcelable {
      *
      * @return true if the device was disconnected, false otherwise and on
      *         error.
+     * @hide
      */
     public boolean removeBond() {
         try {
@@ -205,6 +247,7 @@ public final class BluetoothDevice implements Parcelable {
      *
      * @param address Bluetooth hardware address of the remote device to check.
      * @return Result code
+     * @hide
      */
     public int getBondState() {
         try {
@@ -213,6 +256,7 @@ public final class BluetoothDevice implements Parcelable {
         return BluetoothError.ERROR_IPC;
     }
 
+    /** @hide */
     public int getBluetoothClass() {
         try {
             return sService.getRemoteClass(mAddress);
@@ -220,6 +264,7 @@ public final class BluetoothDevice implements Parcelable {
         return BluetoothError.ERROR_IPC;
     }
 
+    /** @hide */
      public String[] getUuids() {
         try {
             return sService.getRemoteUuids(mAddress);
@@ -227,6 +272,7 @@ public final class BluetoothDevice implements Parcelable {
         return null;
     }
 
+    /** @hide */
     public int getServiceChannel(String uuid) {
          try {
              return sService.getRemoteServiceChannel(mAddress, uuid);
@@ -234,6 +280,7 @@ public final class BluetoothDevice implements Parcelable {
          return BluetoothError.ERROR_IPC;
     }
 
+    /** @hide */
     public boolean setPin(byte[] pin) {
         try {
             return sService.setPin(mAddress, pin);
@@ -241,6 +288,7 @@ public final class BluetoothDevice implements Parcelable {
         return false;
     }
 
+    /** @hide */
     public boolean setPasskey(int passkey) {
         try {
             return sService.setPasskey(mAddress, passkey);
@@ -248,6 +296,7 @@ public final class BluetoothDevice implements Parcelable {
         return false;
     }
 
+    /** @hide */
     public boolean setPairingConfirmation(boolean confirm) {
         try {
             return sService.setPairingConfirmation(mAddress, confirm);
@@ -255,6 +304,7 @@ public final class BluetoothDevice implements Parcelable {
         return false;
     }
 
+    /** @hide */
     public boolean cancelPairingUserInput() {
         try {
             return sService.cancelPairingUserInput(mAddress);
@@ -263,17 +313,20 @@ public final class BluetoothDevice implements Parcelable {
     }
 
     /**
-     * Construct a secure RFCOMM socket ready to start an outgoing connection.
-     * Call #connect on the returned #BluetoothSocket to begin the connection.
-     * The remote device will be authenticated and communication on this socket
-     * will be encrypted.
-     * @param port    remote port
-     * @return an RFCOMM BluetoothSocket
+     * Create an RFCOMM {@link BluetoothSocket} ready to start a secure
+     * outgoing connection to this remote device.
+     * <p>The remote device will be authenticated and communication on this
+     * socket will be encrypted.
+     * <p>Use {@link BluetoothSocket#connect} to intiate the outgoing
+     * connection.
+     * <p>Valid RFCOMM channels are in range 1 to 30.
+     * @param channel RFCOMM channel to connect to
+     * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection
      * @throws IOException on error, for example Bluetooth not available, or
-     *                     insufficient permissions.
+     *                     insufficient permissions
      */
-    public BluetoothSocket createRfcommSocket(int port) throws IOException {
-        return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, port);
+    public BluetoothSocket createRfcommSocket(int channel) throws IOException {
+        return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, channel);
     }
 
     /**
@@ -286,6 +339,7 @@ public final class BluetoothDevice implements Parcelable {
      * @return An RFCOMM BluetoothSocket
      * @throws IOException On error, for example Bluetooth not available, or
      *                     insufficient permissions.
+     * @hide
      */
     public BluetoothSocket createInsecureRfcommSocket(int port) throws IOException {
         return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, false, false, this, port);
@@ -297,6 +351,7 @@ public final class BluetoothDevice implements Parcelable {
      * @return a SCO BluetoothSocket
      * @throws IOException on error, for example Bluetooth not available, or
      *                     insufficient permissions.
+     * @hide
      */
     public BluetoothSocket createScoSocket() throws IOException {
         return new BluetoothSocket(BluetoothSocket.TYPE_SCO, -1, true, true, this, -1);
@@ -309,6 +364,7 @@ public final class BluetoothDevice implements Parcelable {
      * @param pin pin as java String
      * @return the pin code as a UTF8 byte array, or null if it is an invalid
      *         Bluetooth pin.
+     * @hide
      */
     public static byte[] convertPinToBytes(String pin) {
         if (pin == null) {
@@ -327,7 +383,8 @@ public final class BluetoothDevice implements Parcelable {
         return pinBytes;
     }
 
-    /** Sanity check a bluetooth address, such as "00:43:A8:23:10:F0" */
+    /** Sanity check a bluetooth address, such as "00:43:A8:23:10:F0"
+     * @hide */
     public static boolean checkBluetoothAddress(String address) {
         if (address == null || address.length() != ADDRESS_LENGTH) {
             return false;
diff --git a/core/java/android/bluetooth/BluetoothServerSocket.java b/core/java/android/bluetooth/BluetoothServerSocket.java
index 8be300b..e653c23 100644
--- a/core/java/android/bluetooth/BluetoothServerSocket.java
+++ b/core/java/android/bluetooth/BluetoothServerSocket.java
@@ -20,17 +20,31 @@ import java.io.Closeable;
 import java.io.IOException;
 
 /**
- * Server (listening) Bluetooth Socket.
+ * A listening Bluetooth socket.
  *
- * Currently only supports RFCOMM sockets.
+ * <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.
  *
- * 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. RFCOMM is a
+ * connection orientated, streaming transport over Bluetooth. It is also known
+ * as the Serial Port Profile (SPP).
  *
- * TODO: Consider exposing L2CAP sockets.
- * TODO: Clean up javadoc grammer and formatting.
- * TODO: Remove @hide
- * @hide
+ * <p>Use {@link BluetoothDevice#createRfcommSocket} to create a new {@link
+ * BluetoothSocket} ready for an outgoing connection to a remote
+ * {@link BluetoothDevice}.
+ *
+ * <p>Use {@link BluetoothAdapter#listenUsingRfcommOn} to create a listening
+ * {@link BluetoothServerSocket} ready for incoming connections to the local
+ * {@link BluetoothAdapter}.
+ *
+ * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * safe. In particular, {@link #close} will always immediately abort ongoing
+ * operations and close the socket.
  */
 public final class BluetoothServerSocket implements Closeable {
     /*package*/ final BluetoothSocket mSocket;
@@ -51,11 +65,13 @@ public final class BluetoothServerSocket implements Closeable {
 
     /**
      * Block until a connection is established.
-     * Returns a connected #BluetoothSocket. This server socket can be reused
-     * for subsequent incoming connections by calling #accept repeatedly.
-     * #close can be used to abort this call from another thread.
-     * @return A connected #BluetoothSocket
-     * @throws IOException On error, for example this call was aborted
+     * <p>Returns a connected {@link BluetoothSocket} on successful connection.
+     * <p>Once this call returns, it can be called again to accept subsequent
+     * incoming connections.
+     * <p>{@link #close} can be used to abort this call from another thread.
+     * @return a connected {@link BluetoothSocket}
+     * @throws IOException on error, for example this call was aborted, or
+     *                     timeout
      */
     public BluetoothSocket accept() throws IOException {
         return accept(-1);
@@ -63,11 +79,12 @@ public final class BluetoothServerSocket implements Closeable {
 
     /**
      * Block until a connection is established, with timeout.
-     * Returns a connected #BluetoothSocket. This server socket can be reused
-     * for subsequent incoming connections by calling #accept repeatedly.
-     * #close can be used to abort this call from another thread.
-     * @return A connected #BluetoothSocket
-     * @throws IOException On error, for example this call was aborted, or
+     * <p>Returns a connected {@link BluetoothSocket} on successful connection.
+     * <p>Once this call returns, it can be called again to accept subsequent
+     * incoming connections.
+     * <p>{@link #close} can be used to abort this call from another thread.
+     * @return a connected {@link BluetoothSocket}
+     * @throws IOException on error, for example this call was aborted, or
      *                     timeout
      */
     public BluetoothSocket accept(int timeout) throws IOException {
@@ -75,8 +92,8 @@ public final class BluetoothServerSocket implements Closeable {
     }
 
     /**
-     * Closes this socket.
-     * This will cause other blocking calls on this socket to immediately
+     * Immediately close this socket, and release all associated resources.
+     * <p>Causes blocked calls on this socket in other threads to immediately
      * throw an IOException.
      */
     public void close() throws IOException {
diff --git a/core/java/android/bluetooth/BluetoothSocket.java b/core/java/android/bluetooth/BluetoothSocket.java
index dda2cef..eae0f37 100644
--- a/core/java/android/bluetooth/BluetoothSocket.java
+++ b/core/java/android/bluetooth/BluetoothSocket.java
@@ -22,20 +22,34 @@ import java.io.InputStream;
 import java.io.OutputStream;
 
 /**
- * Represents a connected or connecting Bluetooth Socket.
+ * A connected or connecting Bluetooth socket.
  *
- * Currently only supports RFCOMM sockets.
+ * <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.
  *
- * 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. RFCOMM is a
+ * connection orientated, streaming transport over Bluetooth. It is also known
+ * as the Serial Port Profile (SPP).
  *
- * TODO: Consider exposing L2CAP sockets.
- * TODO: Clean up javadoc grammer and formatting.
- * TODO: Remove @hide
- * @hide
+ * <p>Use {@link BluetoothDevice#createRfcommSocket} to create a new {@link
+ * BluetoothSocket} ready for an outgoing connection to a remote
+ * {@link BluetoothDevice}.
+ *
+ * <p>Use {@link BluetoothAdapter#listenUsingRfcommOn} to create a listening
+ * {@link BluetoothServerSocket} ready for incoming connections to the local
+ * {@link BluetoothAdapter}.
+ *
+ * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * safe. In particular, {@link #close} will always immediately abort ongoing
+ * operations and close the socket.
  */
 public final class BluetoothSocket implements Closeable {
-    /** Keep TYPE_RFCOMM etc in sync with BluetoothSocket.cpp */
+    /** Keep TYPE_ fields in sync with BluetoothSocket.cpp */
     /*package*/ static final int TYPE_RFCOMM = 1;
     /*package*/ static final int TYPE_SCO = 2;
     /*package*/ static final int TYPE_L2CAP = 3;
@@ -99,6 +113,7 @@ public final class BluetoothSocket implements Closeable {
         this(type, fd, auth, encrypt, new BluetoothDevice(address), port);
     }
 
+    /** @hide */
     @Override
     protected void finalize() throws Throwable {
         try {
@@ -110,19 +125,19 @@ public final class BluetoothSocket implements Closeable {
 
     /**
      * Attempt to connect to a remote device.
-     * This method will block until a connection is made or the connection
+     * <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. #close can be used to abort this call from another
-     * thread.
-     * @throws IOException On error, for example connection failure
+     * is now connected.
+     * <p>{@link #close} can be used to abort this call from another thread.
+     * @throws IOException on error, for example connection failure
      */
     public void connect() throws IOException {
         connectNative();
     }
 
     /**
-     * Closes this socket.
-     * This will cause other blocking calls on this socket to immediately
+     * Immediately close this socket, and release all associated resources.
+     * <p>Causes blocked calls on this socket in other threads to immediately
      * throw an IOException.
      */
     public void close() throws IOException {
@@ -130,9 +145,8 @@ public final class BluetoothSocket implements Closeable {
     }
 
     /**
-     * Return the remote device we are connecting, or connected, to.
-     * @return remote device, or null if this socket has not yet attempted
-     *         or established a connection.
+     * Get the remote device this socket is connecting, or connected, to.
+     * @return remote device
      */
     public BluetoothDevice getRemoteDevice() {
         return mDevice;
@@ -140,7 +154,7 @@ public final class BluetoothSocket implements Closeable {
 
     /**
      * Get the input stream associated with this socket.
-     * The input stream will be returned even if the socket is not yet
+     * <p>The input stream will be returned even if the socket is not yet
      * connected, but operations on that stream will throw IOException until
      * the associated socket is connected.
      * @return InputStream
@@ -151,7 +165,7 @@ public final class BluetoothSocket implements Closeable {
 
     /**
      * Get the output stream associated with this socket.
-     * The output stream will be returned even if the socket is not yet
+     * <p>The output stream will be returned even if the socket is not yet
      * connected, but operations on that stream will throw IOException until
      * the associated socket is connected.
      * @return OutputStream
diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java
index 8ab67c5..d86ab79 100644
--- a/core/java/android/content/Context.java
+++ b/core/java/android/content/Context.java
@@ -1148,7 +1148,6 @@ public abstract class Context {
      *
      * @see #getSystemService
      * @see android.bluetooth.BluetoothAdapter
-     * @hide
      */
     public static final String BLUETOOTH_SERVICE = "bluetooth";
     /**