1 files changed, 84 insertions, 27 deletions

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;