core/java/android/bluetooth/BluetoothDevice.java

   1 /*
   2  * Copyright (C) 2009 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 package android.bluetooth;
  18
  19 import android.annotation.SdkConstant;
  20 import android.annotation.SdkConstant.SdkConstantType;
  21 import android.content.Context;
  22 import android.os.Parcel;
  23 import android.os.Parcelable;
  24 import android.os.ParcelUuid;
  25 import android.os.RemoteException;
  26 import android.util.Log;
  27
  28 import java.io.IOException;
  29 import java.io.UnsupportedEncodingException;
  30 import java.util.UUID;
  31
  32 /**
  33  * Represents a remote Bluetooth device. A {@link BluetoothDevice} lets you
  34  * create a connection with the respective device or query information about
  35  * it, such as the name, address, class, and bonding state.
  36  *
  37  * <p>This class is really just a thin wrapper for a Bluetooth hardware
  38  * address. Objects of this class are immutable. Operations on this class
  39  * are performed on the remote Bluetooth hardware address, using the
  40  * {@link BluetoothAdapter} that was used to create this {@link
  41  * BluetoothDevice}.
  42  *
  43  * <p>To get a {@link BluetoothDevice}, use
  44  * {@link BluetoothAdapter#getRemoteDevice(String)
  45  * BluetoothAdapter.getRemoteDevice(String)} to create one representing a device
  46  * of a known MAC address (which you can get through device discovery with
  47  * {@link BluetoothAdapter}) or get one from the set of bonded devices
  48  * returned by {@link BluetoothAdapter#getBondedDevices()
  49  * BluetoothAdapter.getBondedDevices()}. You can then open a
  50  * {@link BluetoothSocket} for communication with the remote device, using
  51  * {@link #createRfcommSocketToServiceRecord(UUID)}.
  52  *
  53  * <p class="note"><strong>Note:</strong>
  54  * Requires the {@link android.Manifest.permission#BLUETOOTH} permission.
  55  *
  56  * <div class="special reference">
  57  * <h3>Developer Guides</h3>
  58  * <p>For more information about using Bluetooth, read the
  59  * <a href="{@docRoot}guide/topics/wireless/bluetooth.html">Bluetooth</a> developer guide.</p>
  60  * </div>
  61  *
  62  * {@see BluetoothAdapter}
  63  * {@see BluetoothSocket}
  64  */
  65 public final class BluetoothDevice implements Parcelable {
  66     private static final String TAG = "BluetoothDevice";
  67     private static final boolean DBG = false;
  68
  69     /**
  70      * Sentinel error value for this class. Guaranteed to not equal any other
  71      * integer constant in this class. Provided as a convenience for functions
  72      * that require a sentinel error value, for example:
  73      * <p><code>Intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE,
  74      * BluetoothDevice.ERROR)</code>
  75      */
  76     public static final int ERROR = Integer.MIN_VALUE;
  77
  78     /**
  79      * Broadcast Action: Remote device discovered.
  80      * <p>Sent when a remote device is found during discovery.
  81      * <p>Always contains the extra fields {@link #EXTRA_DEVICE} and {@link
  82      * #EXTRA_CLASS}. Can contain the extra fields {@link #EXTRA_NAME} and/or
  83      * {@link #EXTRA_RSSI} if they are available.
  84      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
  85      */
  86      // TODO: Change API to not broadcast RSSI if not available (incoming connection)
  87     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
  88     public static final String ACTION_FOUND =
  89             "android.bluetooth.device.action.FOUND";
  90
  91     /**
  92      * Broadcast Action: Remote device disappeared.
  93      * <p>Sent when a remote device that was found in the last discovery is not
  94      * found in the current discovery.
  95      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
  96      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
  97      * @hide
  98      */
  99     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 100     public static final String ACTION_DISAPPEARED =
 101             "android.bluetooth.device.action.DISAPPEARED";
 102
 103     /**
 104      * Broadcast Action: Bluetooth class of a remote device has changed.
 105      * <p>Always contains the extra fields {@link #EXTRA_DEVICE} and {@link
 106      * #EXTRA_CLASS}.
 107      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 108      * {@see BluetoothClass}
 109      */
 110     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 111     public static final String ACTION_CLASS_CHANGED =
 112             "android.bluetooth.device.action.CLASS_CHANGED";
 113
 114     /**
 115      * Broadcast Action: Indicates a low level (ACL) connection has been
 116      * established with a remote device.
 117      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
 118      * <p>ACL connections are managed automatically by the Android Bluetooth
 119      * stack.
 120      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 121      */
 122     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 123     public static final String ACTION_ACL_CONNECTED =
 124             "android.bluetooth.device.action.ACL_CONNECTED";
 125
 126     /**
 127      * Broadcast Action: Indicates that a low level (ACL) disconnection has
 128      * been requested for a remote device, and it will soon be disconnected.
 129      * <p>This is useful for graceful disconnection. Applications should use
 130      * this intent as a hint to immediately terminate higher level connections
 131      * (RFCOMM, L2CAP, or profile connections) to the remote device.
 132      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
 133      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 134      */
 135     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 136     public static final String ACTION_ACL_DISCONNECT_REQUESTED =
 137             "android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED";
 138
 139     /**
 140      * Broadcast Action: Indicates a low level (ACL) disconnection from a
 141      * remote device.
 142      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
 143      * <p>ACL connections are managed automatically by the Android Bluetooth
 144      * stack.
 145      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 146      */
 147     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 148     public static final String ACTION_ACL_DISCONNECTED =
 149             "android.bluetooth.device.action.ACL_DISCONNECTED";
 150
 151     /**
 152      * Broadcast Action: Indicates the friendly name of a remote device has
 153      * been retrieved for the first time, or changed since the last retrieval.
 154      * <p>Always contains the extra fields {@link #EXTRA_DEVICE} and {@link
 155      * #EXTRA_NAME}.
 156      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 157      */
 158     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 159     public static final String ACTION_NAME_CHANGED =
 160             "android.bluetooth.device.action.NAME_CHANGED";
 161
 162     /**
 163      * Broadcast Action: Indicates the alias of a remote device has been
 164      * changed.
 165      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
 166      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 167      *
 168      * @hide
 169      */
 170     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 171     public static final String ACTION_ALIAS_CHANGED =
 172             "android.bluetooth.device.action.ALIAS_CHANGED";
 173
 174     /**
 175      * Broadcast Action: Indicates a change in the bond state of a remote
 176      * device. For example, if a device is bonded (paired).
 177      * <p>Always contains the extra fields {@link #EXTRA_DEVICE}, {@link
 178      * #EXTRA_BOND_STATE} and {@link #EXTRA_PREVIOUS_BOND_STATE}.
 179      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 180      */
 181     // Note: When EXTRA_BOND_STATE is BOND_NONE then this will also
 182     // contain a hidden extra field EXTRA_REASON with the result code.
 183     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 184     public static final String ACTION_BOND_STATE_CHANGED =
 185             "android.bluetooth.device.action.BOND_STATE_CHANGED";
 186
 187     /**
 188      * Used as a Parcelable {@link BluetoothDevice} extra field in every intent
 189      * broadcast by this class. It contains the {@link BluetoothDevice} that
 190      * the intent applies to.
 191      */
 192     public static final String EXTRA_DEVICE = "android.bluetooth.device.extra.DEVICE";
 193
 194     /**
 195      * Used as a String extra field in {@link #ACTION_NAME_CHANGED} and {@link
 196      * #ACTION_FOUND} intents. It contains the friendly Bluetooth name.
 197      */
 198     public static final String EXTRA_NAME = "android.bluetooth.device.extra.NAME";
 199
 200     /**
 201      * Used as an optional short extra field in {@link #ACTION_FOUND} intents.
 202      * Contains the RSSI value of the remote device as reported by the
 203      * Bluetooth hardware.
 204      */
 205     public static final String EXTRA_RSSI = "android.bluetooth.device.extra.RSSI";
 206
 207     /**
 208      * Used as a Parcelable {@link BluetoothClass} extra field in {@link
 209      * #ACTION_FOUND} and {@link #ACTION_CLASS_CHANGED} intents.
 210      */
 211     public static final String EXTRA_CLASS = "android.bluetooth.device.extra.CLASS";
 212
 213     /**
 214      * Used as an int extra field in {@link #ACTION_BOND_STATE_CHANGED} intents.
 215      * Contains the bond state of the remote device.
 216      * <p>Possible values are:
 217      * {@link #BOND_NONE},
 218      * {@link #BOND_BONDING},
 219      * {@link #BOND_BONDED}.
 220      */
 221     public static final String EXTRA_BOND_STATE = "android.bluetooth.device.extra.BOND_STATE";
 222     /**
 223      * Used as an int extra field in {@link #ACTION_BOND_STATE_CHANGED} intents.
 224      * Contains the previous bond state of the remote device.
 225      * <p>Possible values are:
 226      * {@link #BOND_NONE},
 227      * {@link #BOND_BONDING},
 228      * {@link #BOND_BONDED}.
 229      */
 230     public static final String EXTRA_PREVIOUS_BOND_STATE =
 231             "android.bluetooth.device.extra.PREVIOUS_BOND_STATE";
 232     /**
 233      * Indicates the remote device is not bonded (paired).
 234      * <p>There is no shared link key with the remote device, so communication
 235      * (if it is allowed at all) will be unauthenticated and unencrypted.
 236      */
 237     public static final int BOND_NONE = 10;
 238     /**
 239      * Indicates bonding (pairing) is in progress with the remote device.
 240      */
 241     public static final int BOND_BONDING = 11;
 242     /**
 243      * Indicates the remote device is bonded (paired).
 244      * <p>A shared link keys exists locally for the remote device, so
 245      * communication can be authenticated and encrypted.
 246      * <p><i>Being bonded (paired) with a remote device does not necessarily
 247      * mean the device is currently connected. It just means that the pending
 248      * procedure was completed at some earlier time, and the link key is still
 249      * stored locally, ready to use on the next connection.
 250      * </i>
 251      */
 252     public static final int BOND_BONDED = 12;
 253
 254     /**
 255      * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST}
 256      * intents for unbond reason.
 257      * @hide
 258      */
 259     public static final String EXTRA_REASON = "android.bluetooth.device.extra.REASON";
 260
 261     /**
 262      * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST}
 263      * intents to indicate pairing method used. Possible values are:
 264      * {@link #PAIRING_VARIANT_PIN},
 265      * {@link #PAIRING_VARIANT_PASSKEY_CONFIRMATION},
 266      */
 267     public static final String EXTRA_PAIRING_VARIANT =
 268             "android.bluetooth.device.extra.PAIRING_VARIANT";
 269
 270     /**
 271      * Used as an int extra field in {@link #ACTION_PAIRING_REQUEST}
 272      * intents as the value of passkey.
 273      */
 274     public static final String EXTRA_PAIRING_KEY = "android.bluetooth.device.extra.PAIRING_KEY";
 275
 276     /**
 277      * Bluetooth device type, Unknown
 278      */
 279     public static final int DEVICE_TYPE_UNKNOWN = 0;
 280
 281     /**
 282      * Bluetooth device type, Classic - BR/EDR devices
 283      */
 284     public static final int DEVICE_TYPE_CLASSIC = 1;
 285
 286     /**
 287      * Bluetooth device type, Low Energy - LE-only
 288      */
 289     public static final int DEVICE_TYPE_LE = 2;
 290
 291     /**
 292      * Bluetooth device type, Dual Mode - BR/EDR/LE
 293      */
 294     public static final int DEVICE_TYPE_DUAL = 3;
 295
 296     /**
 297      * Broadcast Action: This intent is used to broadcast the {@link UUID}
 298      * wrapped as a {@link android.os.ParcelUuid} of the remote device after it
 299      * has been fetched. This intent is sent only when the UUIDs of the remote
 300      * device are requested to be fetched using Service Discovery Protocol
 301      * <p> Always contains the extra field {@link #EXTRA_DEVICE}
 302      * <p> Always contains the extra field {@link #EXTRA_UUID}
 303      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 304      */
 305     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 306     public static final String ACTION_UUID =
 307             "android.bluetooth.device.action.UUID";
 308
 309     /** @hide */
 310     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 311     public static final String ACTION_MAS_INSTANCE =
 312             "android.bluetooth.device.action.MAS_INSTANCE";
 313
 314     /**
 315      * Broadcast Action: Indicates a failure to retrieve the name of a remote
 316      * device.
 317      * <p>Always contains the extra field {@link #EXTRA_DEVICE}.
 318      * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
 319      * @hide
 320      */
 321     //TODO: is this actually useful?
 322     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 323     public static final String ACTION_NAME_FAILED =
 324             "android.bluetooth.device.action.NAME_FAILED";
 325
 326     /**
 327      * Broadcast Action: This intent is used to broadcast PAIRING REQUEST
 328      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} to
 329      * receive.
 330      */
 331     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 332     public static final String ACTION_PAIRING_REQUEST =
 333             "android.bluetooth.device.action.PAIRING_REQUEST";
 334     /** @hide */
 335     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 336     public static final String ACTION_PAIRING_CANCEL =
 337             "android.bluetooth.device.action.PAIRING_CANCEL";
 338
 339     /** @hide */
 340     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 341     public static final String ACTION_CONNECTION_ACCESS_REQUEST =
 342             "android.bluetooth.device.action.CONNECTION_ACCESS_REQUEST";
 343
 344     /** @hide */
 345     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 346     public static final String ACTION_CONNECTION_ACCESS_REPLY =
 347             "android.bluetooth.device.action.CONNECTION_ACCESS_REPLY";
 348
 349     /** @hide */
 350     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
 351     public static final String ACTION_CONNECTION_ACCESS_CANCEL =
 352             "android.bluetooth.device.action.CONNECTION_ACCESS_CANCEL";
 353
 354     /**
 355      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REQUEST} intent.
 356      * @hide
 357      */
 358     public static final String EXTRA_ACCESS_REQUEST_TYPE =
 359         "android.bluetooth.device.extra.ACCESS_REQUEST_TYPE";
 360
 361     /**@hide*/
 362     public static final int REQUEST_TYPE_PROFILE_CONNECTION = 1;
 363
 364     /**@hide*/
 365     public static final int REQUEST_TYPE_PHONEBOOK_ACCESS = 2;
 366
 367     /**@hide*/
 368     public static final int REQUEST_TYPE_MESSAGE_ACCESS = 3;
 369
 370     /**
 371      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REQUEST} intents,
 372      * Contains package name to return reply intent to.
 373      * @hide
 374      */
 375     public static final String EXTRA_PACKAGE_NAME = "android.bluetooth.device.extra.PACKAGE_NAME";
 376
 377     /**
 378      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REQUEST} intents,
 379      * Contains class name to return reply intent to.
 380      * @hide
 381      */
 382     public static final String EXTRA_CLASS_NAME = "android.bluetooth.device.extra.CLASS_NAME";
 383
 384     /**
 385      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REPLY} intent.
 386      * @hide
 387      */
 388     public static final String EXTRA_CONNECTION_ACCESS_RESULT =
 389         "android.bluetooth.device.extra.CONNECTION_ACCESS_RESULT";
 390
 391     /**@hide*/
 392     public static final int CONNECTION_ACCESS_YES = 1;
 393
 394     /**@hide*/
 395     public static final int CONNECTION_ACCESS_NO = 2;
 396
 397     /**
 398      * Used as an extra field in {@link #ACTION_CONNECTION_ACCESS_REPLY} intents,
 399      * Contains boolean to indicate if the allowed response is once-for-all so that
 400      * next request will be granted without asking user again.
 401      * @hide
 402      */
 403     public static final String EXTRA_ALWAYS_ALLOWED =
 404         "android.bluetooth.device.extra.ALWAYS_ALLOWED";
 405
 406     /**
 407      * A bond attempt succeeded
 408      * @hide
 409      */
 410     public static final int BOND_SUCCESS = 0;
 411
 412     /**
 413      * A bond attempt failed because pins did not match, or remote device did
 414      * not respond to pin request in time
 415      * @hide
 416      */
 417     public static final int UNBOND_REASON_AUTH_FAILED = 1;
 418
 419     /**
 420      * A bond attempt failed because the other side explicitly rejected
 421      * bonding
 422      * @hide
 423      */
 424     public static final int UNBOND_REASON_AUTH_REJECTED = 2;
 425
 426     /**
 427      * A bond attempt failed because we canceled the bonding process
 428      * @hide
 429      */
 430     public static final int UNBOND_REASON_AUTH_CANCELED = 3;
 431
 432     /**
 433      * A bond attempt failed because we could not contact the remote device
 434      * @hide
 435      */
 436     public static final int UNBOND_REASON_REMOTE_DEVICE_DOWN = 4;
 437
 438     /**
 439      * A bond attempt failed because a discovery is in progress
 440      * @hide
 441      */
 442     public static final int UNBOND_REASON_DISCOVERY_IN_PROGRESS = 5;
 443
 444     /**
 445      * A bond attempt failed because of authentication timeout
 446      * @hide
 447      */
 448     public static final int UNBOND_REASON_AUTH_TIMEOUT = 6;
 449
 450     /**
 451      * A bond attempt failed because of repeated attempts
 452      * @hide
 453      */
 454     public static final int UNBOND_REASON_REPEATED_ATTEMPTS = 7;
 455
 456     /**
 457      * A bond attempt failed because we received an Authentication Cancel
 458      * by remote end
 459      * @hide
 460      */
 461     public static final int UNBOND_REASON_REMOTE_AUTH_CANCELED = 8;
 462
 463     /**
 464      * An existing bond was explicitly revoked
 465      * @hide
 466      */
 467     public static final int UNBOND_REASON_REMOVED = 9;
 468
 469     /**
 470      * The user will be prompted to enter a pin or
 471      * an app will enter a pin for user.
 472      */
 473     public static final int PAIRING_VARIANT_PIN = 0;
 474
 475     /**
 476      * The user will be prompted to enter a passkey
 477      * @hide
 478      */
 479     public static final int PAIRING_VARIANT_PASSKEY = 1;
 480
 481     /**
 482      * The user will be prompted to confirm the passkey displayed on the screen or
 483      * an app will confirm the passkey for the user.
 484      */
 485     public static final int PAIRING_VARIANT_PASSKEY_CONFIRMATION = 2;
 486
 487     /**
 488      * The user will be prompted to accept or deny the incoming pairing request
 489      * @hide
 490      */
 491     public static final int PAIRING_VARIANT_CONSENT = 3;
 492
 493     /**
 494      * The user will be prompted to enter the passkey displayed on remote device
 495      * This is used for Bluetooth 2.1 pairing.
 496      * @hide
 497      */
 498     public static final int PAIRING_VARIANT_DISPLAY_PASSKEY = 4;
 499
 500     /**
 501      * The user will be prompted to enter the PIN displayed on remote device.
 502      * This is used for Bluetooth 2.0 pairing.
 503      * @hide
 504      */
 505     public static final int PAIRING_VARIANT_DISPLAY_PIN = 5;
 506
 507     /**
 508      * The user will be prompted to accept or deny the OOB pairing request
 509      * @hide
 510      */
 511     public static final int PAIRING_VARIANT_OOB_CONSENT = 6;
 512
 513     /**
 514      * Used as an extra field in {@link #ACTION_UUID} intents,
 515      * Contains the {@link android.os.ParcelUuid}s of the remote device which
 516      * is a parcelable version of {@link UUID}.
 517      */
 518     public static final String EXTRA_UUID = "android.bluetooth.device.extra.UUID";
 519
 520     /**
 521      * For {@link #getPhonebookAccessPermission}, {@link #setPhonebookAccessPermission},
 522      * {@link #getMessageAccessPermission} and {@link #setMessageAccessPermission}.
 523      * @hide
 524      */
 525     public static final int ACCESS_UNKNOWN = 0;
 526
 527     /**
 528      * For {@link #getPhonebookAccessPermission}, {@link #setPhonebookAccessPermission},
 529      * {@link #getMessageAccessPermission} and {@link #setMessageAccessPermission}.
 530      * @hide
 531      */
 532     public static final int ACCESS_ALLOWED = 1;
 533
 534     /**
 535      * For {@link #getPhonebookAccessPermission}, {@link #setPhonebookAccessPermission},
 536      * {@link #getMessageAccessPermission} and {@link #setMessageAccessPermission}.
 537      * @hide
 538      */
 539     public static final int ACCESS_REJECTED = 2;
 540
 541      /**
 542       * No preferrence of physical transport for GATT connections to remote dual-mode devices
 543       * @hide
 544       */
 545     public static final int TRANSPORT_AUTO = 0;
 546
 547     /**
 548      * Prefer BR/EDR transport for GATT connections to remote dual-mode devices
 549      * @hide
 550      */
 551     public static final int TRANSPORT_BREDR = 1;
 552
 553     /**
 554      * Prefer LE transport for GATT connections to remote dual-mode devices
 555      * @hide
 556      */
 557     public static final int TRANSPORT_LE = 2;
 558
 559     /** @hide */
 560     public static final String EXTRA_MAS_INSTANCE =
 561         "android.bluetooth.device.extra.MAS_INSTANCE";
 562
 563     /**
 564      * Lazy initialization. Guaranteed final after first object constructed, or
 565      * getService() called.
 566      * TODO: Unify implementation of sService amongst BluetoothFoo API's
 567      */
 568     private static IBluetooth sService;
 569
 570     private final String mAddress;
 571
 572     /*package*/ static IBluetooth getService() {
 573         synchronized (BluetoothDevice.class) {
 574             if (sService == null) {
 575                 BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
 576                 sService = adapter.getBluetoothService(mStateChangeCallback);
 577             }
 578         }
 579         return sService;
 580     }
 581
 582     static IBluetoothManagerCallback mStateChangeCallback = new IBluetoothManagerCallback.Stub() {
 583
 584         public void onBluetoothServiceUp(IBluetooth bluetoothService)
 585                 throws RemoteException {
 586             synchronized (BluetoothDevice.class) {
 587                 sService = bluetoothService;
 588             }
 589         }
 590
 591         public void onBluetoothServiceDown()
 592             throws RemoteException {
 593             synchronized (BluetoothDevice.class) {
 594                 sService = null;
 595             }
 596         }
 597     };
 598     /**
 599      * Create a new BluetoothDevice
 600      * Bluetooth MAC address must be upper case, such as "00:11:22:33:AA:BB",
 601      * and is validated in this constructor.
 602      * @param address valid Bluetooth MAC address
 603      * @throws RuntimeException Bluetooth is not available on this platform
 604      * @throws IllegalArgumentException address is invalid
 605      * @hide
 606      */
 607     /*package*/ BluetoothDevice(String address) {
 608         getService();  // ensures sService is initialized
 609         if (!BluetoothAdapter.checkBluetoothAddress(address)) {
 610             throw new IllegalArgumentException(address + " is not a valid Bluetooth address");
 611         }
 612
 613         mAddress = address;
 614     }
 615
 616     @Override
 617     public boolean equals(Object o) {
 618         if (o instanceof BluetoothDevice) {
 619             return mAddress.equals(((BluetoothDevice)o).getAddress());
 620         }
 621         return false;
 622     }
 623
 624     @Override
 625     public int hashCode() {
 626         return mAddress.hashCode();
 627     }
 628
 629     /**
 630      * Returns a string representation of this BluetoothDevice.
 631      * <p>Currently this is the Bluetooth hardware address, for example
 632      * "00:11:22:AA:BB:CC". However, you should always use {@link #getAddress}
 633      * if you explicitly require the Bluetooth hardware address in case the
 634      * {@link #toString} representation changes in the future.
 635      * @return string representation of this BluetoothDevice
 636      */
 637     @Override
 638     public String toString() {
 639         return mAddress;
 640     }
 641
 642     public int describeContents() {
 643         return 0;
 644     }
 645
 646     public static final Parcelable.Creator<BluetoothDevice> CREATOR =
 647             new Parcelable.Creator<BluetoothDevice>() {
 648         public BluetoothDevice createFromParcel(Parcel in) {
 649             return new BluetoothDevice(in.readString());
 650         }
 651         public BluetoothDevice[] newArray(int size) {
 652             return new BluetoothDevice[size];
 653         }
 654     };
 655
 656     public void writeToParcel(Parcel out, int flags) {
 657         out.writeString(mAddress);
 658     }
 659
 660     /**
 661      * Returns the hardware address of this BluetoothDevice.
 662      * <p> For example, "00:11:22:AA:BB:CC".
 663      * @return Bluetooth hardware address as string
 664      */
 665     public String getAddress() {
 666         if (DBG) Log.d(TAG, "mAddress: " + mAddress);
 667         return mAddress;
 668     }
 669
 670     /**
 671      * Get the friendly Bluetooth name of the remote device.
 672      *
 673      * <p>The local adapter will automatically retrieve remote names when
 674      * performing a device scan, and will cache them. This method just returns
 675      * the name for this device from the cache.
 676      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
 677      *
 678      * @return the Bluetooth name, or null if there was a problem.
 679      */
 680     public String getName() {
 681         if (sService == null) {
 682             Log.e(TAG, "BT not enabled. Cannot get Remote Device name");
 683             return null;
 684         }
 685         try {
 686             return sService.getRemoteName(this);
 687         } catch (RemoteException e) {Log.e(TAG, "", e);}
 688         return null;
 689     }
 690
 691     /**
 692      * Get the Bluetooth device type of the remote device.
 693      *
 694      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
 695      *
 696      * @return the device type {@link #DEVICE_TYPE_CLASSIC}, {@link #DEVICE_TYPE_LE}
 697      *                         {@link #DEVICE_TYPE_DUAL}.
 698      *         {@link #DEVICE_TYPE_UNKNOWN} if it's not available
 699      */
 700     public int getType() {
 701         if (sService == null) {
 702             Log.e(TAG, "BT not enabled. Cannot get Remote Device type");
 703             return DEVICE_TYPE_UNKNOWN;
 704         }
 705         try {
 706             return sService.getRemoteType(this);
 707         } catch (RemoteException e) {Log.e(TAG, "", e);}
 708         return DEVICE_TYPE_UNKNOWN;
 709     }
 710
 711     /**
 712      * Get the Bluetooth alias of the remote device.
 713      * <p>Alias is the locally modified name of a remote device.
 714      *
 715      * @return the Bluetooth alias, or null if no alias or there was a problem
 716      * @hide
 717      */
 718     public String getAlias() {
 719         if (sService == null) {
 720             Log.e(TAG, "BT not enabled. Cannot get Remote Device Alias");
 721             return null;
 722         }
 723         try {
 724             return sService.getRemoteAlias(this);
 725         } catch (RemoteException e) {Log.e(TAG, "", e);}
 726         return null;
 727     }
 728
 729     /**
 730      * Set the Bluetooth alias of the remote device.
 731      * <p>Alias is the locally modified name of a remote device.
 732      * <p>This methoid overwrites the alias. The changed
 733      * alias is saved in the local storage so that the change
 734      * is preserved over power cycle.
 735      *
 736      * @return true on success, false on error
 737      * @hide
 738      */
 739     public boolean setAlias(String alias) {
 740         if (sService == null) {
 741             Log.e(TAG, "BT not enabled. Cannot set Remote Device name");
 742             return false;
 743         }
 744         try {
 745             return sService.setRemoteAlias(this, alias);
 746         } catch (RemoteException e) {Log.e(TAG, "", e);}
 747         return false;
 748     }
 749
 750     /**
 751      * Get the Bluetooth alias of the remote device.
 752      * If Alias is null, get the Bluetooth name instead.
 753      * @see #getAlias()
 754      * @see #getName()
 755      *
 756      * @return the Bluetooth alias, or null if no alias or there was a problem
 757      * @hide
 758      */
 759     public String getAliasName() {
 760         String name = getAlias();
 761         if (name == null) {
 762             name = getName();
 763         }
 764         return name;
 765     }
 766
 767     /**
 768      * Start the bonding (pairing) process with the remote device.
 769      * <p>This is an asynchronous call, it will return immediately. Register
 770      * for {@link #ACTION_BOND_STATE_CHANGED} intents to be notified when
 771      * the bonding process completes, and its result.
 772      * <p>Android system services will handle the necessary user interactions
 773      * to confirm and complete the bonding process.
 774      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 775      *
 776      * @return false on immediate error, true if bonding will begin
 777      */
 778     public boolean createBond() {
 779         if (sService == null) {
 780             Log.e(TAG, "BT not enabled. Cannot create bond to Remote Device");
 781             return false;
 782         }
 783         try {
 784             return sService.createBond(this, TRANSPORT_AUTO);
 785         } catch (RemoteException e) {Log.e(TAG, "", e);}
 786         return false;
 787     }
 788
 789     /**
 790      * Start the bonding (pairing) process with the remote device using the
 791      * specified transport.
 792      *
 793      * <p>This is an asynchronous call, it will return immediately. Register
 794      * for {@link #ACTION_BOND_STATE_CHANGED} intents to be notified when
 795      * the bonding process completes, and its result.
 796      * <p>Android system services will handle the necessary user interactions
 797      * to confirm and complete the bonding process.
 798      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 799      *
 800      * @param transport The transport to use for the pairing procedure.
 801      * @return false on immediate error, true if bonding will begin
 802      * @throws IllegalArgumentException if an invalid transport was specified
 803      * @hide
 804      */
 805     public boolean createBond(int transport) {
 806         if (sService == null) {
 807             Log.e(TAG, "BT not enabled. Cannot create bond to Remote Device");
 808             return false;
 809         }
 810         if (TRANSPORT_AUTO > transport || transport > TRANSPORT_LE)
 811         {
 812             throw new IllegalArgumentException(transport + " is not a valid Bluetooth transport");
 813         }
 814         try {
 815             return sService.createBond(this, transport);
 816         } catch (RemoteException e) {Log.e(TAG, "", e);}
 817         return false;
 818     }
 819
 820     /**
 821      * Start the bonding (pairing) process with the remote device using the
 822      * Out Of Band mechanism.
 823      *
 824      * <p>This is an asynchronous call, it will return immediately. Register
 825      * for {@link #ACTION_BOND_STATE_CHANGED} intents to be notified when
 826      * the bonding process completes, and its result.
 827      *
 828      * <p>Android system services will handle the necessary user interactions
 829      * to confirm and complete the bonding process.
 830      *
 831      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 832      *
 833      * @param hash - Simple Secure pairing hash
 834      * @param randomizer - The random key obtained using OOB
 835      * @return false on immediate error, true if bonding will begin
 836      *
 837      * @hide
 838      */
 839     public boolean createBondOutOfBand(byte[] hash, byte[] randomizer) {
 840         //TODO(BT)
 841         /*
 842         try {
 843             return sService.createBondOutOfBand(this, hash, randomizer);
 844         } catch (RemoteException e) {Log.e(TAG, "", e);}*/
 845         return false;
 846     }
 847
 848     /**
 849      * Set the Out Of Band data for a remote device to be used later
 850      * in the pairing mechanism. Users can obtain this data through other
 851      * trusted channels
 852      *
 853      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 854      *
 855      * @param hash Simple Secure pairing hash
 856      * @param randomizer The random key obtained using OOB
 857      * @return false on error; true otherwise
 858      *
 859      * @hide
 860      */
 861     public boolean setDeviceOutOfBandData(byte[] hash, byte[] randomizer) {
 862       //TODO(BT)
 863       /*
 864       try {
 865         return sService.setDeviceOutOfBandData(this, hash, randomizer);
 866       } catch (RemoteException e) {Log.e(TAG, "", e);} */
 867       return false;
 868     }
 869
 870     /**
 871      * Cancel an in-progress bonding request started with {@link #createBond}.
 872      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 873      *
 874      * @return true on success, false on error
 875      * @hide
 876      */
 877     public boolean cancelBondProcess() {
 878         if (sService == null) {
 879             Log.e(TAG, "BT not enabled. Cannot cancel Remote Device bond");
 880             return false;
 881         }
 882         try {
 883             return sService.cancelBondProcess(this);
 884         } catch (RemoteException e) {Log.e(TAG, "", e);}
 885         return false;
 886     }
 887
 888     /**
 889      * Remove bond (pairing) with the remote device.
 890      * <p>Delete the link key associated with the remote device, and
 891      * immediately terminate connections to that device that require
 892      * authentication and encryption.
 893      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
 894      *
 895      * @return true on success, false on error
 896      * @hide
 897      */
 898     public boolean removeBond() {
 899         if (sService == null) {
 900             Log.e(TAG, "BT not enabled. Cannot remove Remote Device bond");
 901             return false;
 902         }
 903         try {
 904             return sService.removeBond(this);
 905         } catch (RemoteException e) {Log.e(TAG, "", e);}
 906         return false;
 907     }
 908
 909     /**
 910      * Get the bond state of the remote device.
 911      * <p>Possible values for the bond state are:
 912      * {@link #BOND_NONE},
 913      * {@link #BOND_BONDING},
 914      * {@link #BOND_BONDED}.
 915      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
 916      *
 917      * @return the bond state
 918      */
 919     public int getBondState() {
 920         if (sService == null) {
 921             Log.e(TAG, "BT not enabled. Cannot get bond state");
 922             return BOND_NONE;
 923         }
 924         try {
 925             return sService.getBondState(this);
 926         } catch (RemoteException e) {Log.e(TAG, "", e);}
 927         catch (NullPointerException npe) {
 928             // Handle case where bluetooth service proxy
 929             // is already null.
 930             Log.e(TAG, "NullPointerException for getBondState() of device ("+
 931                 getAddress()+")", npe);
 932         }
 933         return BOND_NONE;
 934     }
 935
 936     /**
 937      * Returns whether there is an open connection to this device.
 938      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
 939      *
 940      * @return True if there is at least one open connection to this device.
 941      * @hide
 942      */
 943     public boolean isConnected() {
 944         if (sService == null) {
 945             // BT is not enabled, we cannot be connected.
 946             return false;
 947         }
 948         try {
 949             return sService.isConnected(this);
 950         } catch (RemoteException e) {
 951             Log.e(TAG, "", e);
 952             return false;
 953         }
 954     }
 955
 956     /**
 957      * Get the Bluetooth class of the remote device.
 958      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
 959      *
 960      * @return Bluetooth class object, or null on error
 961      */
 962     public BluetoothClass getBluetoothClass() {
 963         if (sService == null) {
 964             Log.e(TAG, "BT not enabled. Cannot get Bluetooth Class");
 965             return null;
 966         }
 967         try {
 968             int classInt = sService.getRemoteClass(this);
 969             if (classInt == BluetoothClass.ERROR) return null;
 970             return new BluetoothClass(classInt);
 971         } catch (RemoteException e) {Log.e(TAG, "", e);}
 972         return null;
 973     }
 974
 975     /**
 976      * Returns the supported features (UUIDs) of the remote device.
 977      *
 978      * <p>This method does not start a service discovery procedure to retrieve the UUIDs
 979      * from the remote device. Instead, the local cached copy of the service
 980      * UUIDs are returned.
 981      * <p>Use {@link #fetchUuidsWithSdp} if fresh UUIDs are desired.
 982      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
 983      *
 984      * @return the supported features (UUIDs) of the remote device,
 985      *         or null on error
 986      */
 987      public ParcelUuid[] getUuids() {
 988          if (sService == null) {
 989             Log.e(TAG, "BT not enabled. Cannot get remote device Uuids");
 990              return null;
 991          }
 992         try {
 993             return sService.getRemoteUuids(this);
 994         } catch (RemoteException e) {Log.e(TAG, "", e);}
 995         return null;
 996     }
 997
 998      /**
 999       * Perform a service discovery on the remote device to get the UUIDs supported.
1000       *
1001       * <p>This API is asynchronous and {@link #ACTION_UUID} intent is sent,
1002       * with the UUIDs supported by the remote end. If there is an error
1003       * in getting the SDP records or if the process takes a long time,
1004       * {@link #ACTION_UUID} intent is sent with the UUIDs that is currently
1005       * present in the cache. Clients should use the {@link #getUuids} to get UUIDs
1006       * if service discovery is not to be performed.
1007       * <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
1008       *
1009       * @return False if the sanity check fails, True if the process
1010       *               of initiating an ACL connection to the remote device
1011       *               was started.
1012       */
1013      public boolean fetchUuidsWithSdp() {
1014         IBluetooth service = sService;
1015         if (service == null) {
1016             Log.e(TAG, "BT not enabled. Cannot fetchUuidsWithSdp");
1017             return false;
1018         }
1019         try {
1020             return service.fetchRemoteUuids(this);
1021         } catch (RemoteException e) {Log.e(TAG, "", e);}
1022             return false;
1023     }
1024
1025      /** @hide */
1026      public boolean fetchMasInstances() {
1027          if (sService == null) {
1028              Log.e(TAG, "BT not enabled. Cannot query remote device for MAS instances");
1029              return false;
1030          }
1031          try {
1032              return sService.fetchRemoteMasInstances(this);
1033          } catch (RemoteException e) {Log.e(TAG, "", e);}
1034          return false;
1035      }
1036
1037     /** @hide */
1038     public int getServiceChannel(ParcelUuid uuid) {
1039         //TODO(BT)
1040         /*
1041          try {
1042              return sService.getRemoteServiceChannel(this, uuid);
1043          } catch (RemoteException e) {Log.e(TAG, "", e);}*/
1044          return BluetoothDevice.ERROR;
1045     }
1046
1047     /**
1048      * Set the pin during pairing when the pairing method is {@link #PAIRING_VARIANT_PIN}
1049      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
1050      *
1051      * @return true pin has been set
1052      *         false for error
1053      */
1054     public boolean setPin(byte[] pin) {
1055         if (sService == null) {
1056             Log.e(TAG, "BT not enabled. Cannot set Remote Device pin");
1057             return false;
1058         }
1059         try {
1060             return sService.setPin(this, true, pin.length, pin);
1061         } catch (RemoteException e) {Log.e(TAG, "", e);}
1062         return false;
1063     }
1064
1065     /** @hide */
1066     public boolean setPasskey(int passkey) {
1067         //TODO(BT)
1068         /*
1069         try {
1070             return sService.setPasskey(this, true, 4, passkey);
1071         } catch (RemoteException e) {Log.e(TAG, "", e);}*/
1072         return false;
1073     }
1074
1075     /**
1076      * Confirm passkey for {@link #PAIRING_VARIANT_PASSKEY_CONFIRMATION} pairing.
1077      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}.
1078      *
1079      * @return true confirmation has been sent out
1080      *         false for error
1081      */
1082     public boolean setPairingConfirmation(boolean confirm) {
1083         if (sService == null) {
1084             Log.e(TAG, "BT not enabled. Cannot set pairing confirmation");
1085             return false;
1086         }
1087         try {
1088             return sService.setPairingConfirmation(this, confirm);
1089         } catch (RemoteException e) {Log.e(TAG, "", e);}
1090         return false;
1091     }
1092
1093     /** @hide */
1094     public boolean setRemoteOutOfBandData() {
1095         // TODO(BT)
1096         /*
1097         try {
1098           return sService.setRemoteOutOfBandData(this);
1099       } catch (RemoteException e) {Log.e(TAG, "", e);}*/
1100       return false;
1101     }
1102
1103     /** @hide */
1104     public boolean cancelPairingUserInput() {
1105         if (sService == null) {
1106             Log.e(TAG, "BT not enabled. Cannot create pairing user input");
1107             return false;
1108         }
1109         try {
1110             return sService.cancelBondProcess(this);
1111         } catch (RemoteException e) {Log.e(TAG, "", e);}
1112         return false;
1113     }
1114
1115     /** @hide */
1116     public boolean isBluetoothDock() {
1117         // TODO(BT)
1118         /*
1119         try {
1120             return sService.isBluetoothDock(this);
1121         } catch (RemoteException e) {Log.e(TAG, "", e);}*/
1122         return false;
1123     }
1124
1125     /**
1126      * Requires {@link android.Manifest.permission#BLUETOOTH}.
1127      * @return Whether the phonebook access is allowed to this device. Can be
1128      *         {@link #ACCESS_UNKNOWN}, {@link #ACCESS_ALLOWED} or {@link #ACCESS_REJECTED}.
1129      * @hide
1130      */
1131     public int getPhonebookAccessPermission() {
1132         if (sService == null) {
1133             return ACCESS_UNKNOWN;
1134         }
1135         try {
1136             return sService.getPhonebookAccessPermission(this);
1137         } catch (RemoteException e) {
1138             Log.e(TAG, "", e);
1139         }
1140         return ACCESS_UNKNOWN;
1141     }
1142
1143     /**
1144      * Sets whether the phonebook access is allowed to this device.
1145      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_PRIVILEGED}.
1146      * @param value Can be {@link #ACCESS_UNKNOWN}, {@link #ACCESS_ALLOWED} or
1147      *              {@link #ACCESS_REJECTED}.
1148      * @return Whether the value has been successfully set.
1149      * @hide
1150      */
1151     public boolean setPhonebookAccessPermission(int value) {
1152         if (sService == null) {
1153             return false;
1154         }
1155         try {
1156             return sService.setPhonebookAccessPermission(this, value);
1157         } catch (RemoteException e) {
1158             Log.e(TAG, "", e);
1159         }
1160         return false;
1161     }
1162
1163     /**
1164      * Requires {@link android.Manifest.permission#BLUETOOTH}.
1165      * @return Whether the message access is allowed to this device. Can be
1166      *         {@link #ACCESS_UNKNOWN}, {@link #ACCESS_ALLOWED} or {@link #ACCESS_REJECTED}.
1167      * @hide
1168      */
1169     public int getMessageAccessPermission() {
1170         if (sService == null) {
1171             return ACCESS_UNKNOWN;
1172         }
1173         try {
1174             return sService.getMessageAccessPermission(this);
1175         } catch (RemoteException e) {
1176             Log.e(TAG, "", e);
1177         }
1178         return ACCESS_UNKNOWN;
1179     }
1180
1181     /**
1182      * Sets whether the message access is allowed to this device.
1183      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_PRIVILEGED}.
1184      * @param value Can be {@link #ACCESS_UNKNOWN}, {@link #ACCESS_ALLOWED} or
1185      *              {@link #ACCESS_REJECTED}.
1186      * @return Whether the value has been successfully set.
1187      * @hide
1188      */
1189     public boolean setMessageAccessPermission(int value) {
1190         if (sService == null) {
1191             return false;
1192         }
1193         try {
1194             return sService.setMessageAccessPermission(this, value);
1195         } catch (RemoteException e) {
1196             Log.e(TAG, "", e);
1197         }
1198         return false;
1199     }
1200
1201     /**
1202      * Create an RFCOMM {@link BluetoothSocket} ready to start a secure
1203      * outgoing connection to this remote device on given channel.
1204      * <p>The remote device will be authenticated and communication on this
1205      * socket will be encrypted.
1206      * <p> Use this socket only if an authenticated socket link is possible.
1207      * Authentication refers to the authentication of the link key to
1208      * prevent man-in-the-middle type of attacks.
1209      * For example, for Bluetooth 2.1 devices, if any of the devices does not
1210      * have an input and output capability or just has the ability to
1211      * display a numeric key, a secure socket connection is not possible.
1212      * In such a case, use {#link createInsecureRfcommSocket}.
1213      * For more details, refer to the Security Model section 5.2 (vol 3) of
1214      * Bluetooth Core Specification version 2.1 + EDR.
1215      * <p>Use {@link BluetoothSocket#connect} to initiate the outgoing
1216      * connection.
1217      * <p>Valid RFCOMM channels are in range 1 to 30.
1218      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
1219      *
1220      * @param channel RFCOMM channel to connect to
1221      * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection
1222      * @throws IOException on error, for example Bluetooth not available, or
1223      *                     insufficient permissions
1224      * @hide
1225      */
1226     public BluetoothSocket createRfcommSocket(int channel) throws IOException {
1227         return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, channel,
1228                 null);
1229     }
1230
1231     /**
1232      * Create an RFCOMM {@link BluetoothSocket} ready to start a secure
1233      * outgoing connection to this remote device using SDP lookup of uuid.
1234      * <p>This is designed to be used with {@link
1235      * BluetoothAdapter#listenUsingRfcommWithServiceRecord} for peer-peer
1236      * Bluetooth applications.
1237      * <p>Use {@link BluetoothSocket#connect} to initiate the outgoing
1238      * connection. This will also perform an SDP lookup of the given uuid to
1239      * determine which channel to connect to.
1240      * <p>The remote device will be authenticated and communication on this
1241      * socket will be encrypted.
1242      * <p> Use this socket only if an authenticated socket link is possible.
1243      * Authentication refers to the authentication of the link key to
1244      * prevent man-in-the-middle type of attacks.
1245      * For example, for Bluetooth 2.1 devices, if any of the devices does not
1246      * have an input and output capability or just has the ability to
1247      * display a numeric key, a secure socket connection is not possible.
1248      * In such a case, use {#link createInsecureRfcommSocketToServiceRecord}.
1249      * For more details, refer to the Security Model section 5.2 (vol 3) of
1250      * Bluetooth Core Specification version 2.1 + EDR.
1251      * <p>Hint: If you are connecting to a Bluetooth serial board then try
1252      * using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.
1253      * However if you are connecting to an Android peer then please generate
1254      * your own unique UUID.
1255      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
1256      *
1257      * @param uuid service record uuid to lookup RFCOMM channel
1258      * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection
1259      * @throws IOException on error, for example Bluetooth not available, or
1260      *                     insufficient permissions
1261      */
1262     public BluetoothSocket createRfcommSocketToServiceRecord(UUID uuid) throws IOException {
1263         return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, true, true, this, -1,
1264                 new ParcelUuid(uuid));
1265     }
1266
1267     /**
1268      * Create an RFCOMM {@link BluetoothSocket} socket ready to start an insecure
1269      * outgoing connection to this remote device using SDP lookup of uuid.
1270      * <p> The communication channel will not have an authenticated link key
1271      * i.e it will be subject to man-in-the-middle attacks. For Bluetooth 2.1
1272      * devices, the link key will be encrypted, as encryption is mandatory.
1273      * For legacy devices (pre Bluetooth 2.1 devices) the link key will
1274      * be not be encrypted. Use {@link #createRfcommSocketToServiceRecord} if an
1275      * encrypted and authenticated communication channel is desired.
1276      * <p>This is designed to be used with {@link
1277      * BluetoothAdapter#listenUsingInsecureRfcommWithServiceRecord} for peer-peer
1278      * Bluetooth applications.
1279      * <p>Use {@link BluetoothSocket#connect} to initiate the outgoing
1280      * connection. This will also perform an SDP lookup of the given uuid to
1281      * determine which channel to connect to.
1282      * <p>The remote device will be authenticated and communication on this
1283      * socket will be encrypted.
1284      * <p>Hint: If you are connecting to a Bluetooth serial board then try
1285      * using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.
1286      * However if you are connecting to an Android peer then please generate
1287      * your own unique UUID.
1288      * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
1289      *
1290      * @param uuid service record uuid to lookup RFCOMM channel
1291      * @return a RFCOMM BluetoothServerSocket ready for an outgoing connection
1292      * @throws IOException on error, for example Bluetooth not available, or
1293      *                     insufficient permissions
1294      */
1295     public BluetoothSocket createInsecureRfcommSocketToServiceRecord(UUID uuid) throws IOException {
1296         return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, false, false, this, -1,
1297                 new ParcelUuid(uuid));
1298     }
1299
1300     /**
1301      * Construct an insecure RFCOMM socket ready to start an outgoing
1302      * connection.
1303      * Call #connect on the returned #BluetoothSocket to begin the connection.
1304      * The remote device will not be authenticated and communication on this
1305      * socket will not be encrypted.
1306      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
1307      *
1308      * @param port    remote port
1309      * @return An RFCOMM BluetoothSocket
1310      * @throws IOException On error, for example Bluetooth not available, or
1311      *                     insufficient permissions.
1312      * @hide
1313      */
1314     public BluetoothSocket createInsecureRfcommSocket(int port) throws IOException {
1315         return new BluetoothSocket(BluetoothSocket.TYPE_RFCOMM, -1, false, false, this, port,
1316                 null);
1317     }
1318
1319     /**
1320      * Construct a SCO socket ready to start an outgoing connection.
1321      * Call #connect on the returned #BluetoothSocket to begin the connection.
1322      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
1323      *
1324      * @return a SCO BluetoothSocket
1325      * @throws IOException on error, for example Bluetooth not available, or
1326      *                     insufficient permissions.
1327      * @hide
1328      */
1329     public BluetoothSocket createScoSocket() throws IOException {
1330         return new BluetoothSocket(BluetoothSocket.TYPE_SCO, -1, true, true, this, -1, null);
1331     }
1332
1333     /**
1334      * Check that a pin is valid and convert to byte array.
1335      *
1336      * Bluetooth pin's are 1 to 16 bytes of UTF-8 characters.
1337      * @param pin pin as java String
1338      * @return the pin code as a UTF-8 byte array, or null if it is an invalid
1339      *         Bluetooth pin.
1340      * @hide
1341      */
1342     public static byte[] convertPinToBytes(String pin) {
1343         if (pin == null) {
1344             return null;
1345         }
1346         byte[] pinBytes;
1347         try {
1348             pinBytes = pin.getBytes("UTF-8");
1349         } catch (UnsupportedEncodingException uee) {
1350             Log.e(TAG, "UTF-8 not supported?!?");  // this should not happen
1351             return null;
1352         }
1353         if (pinBytes.length <= 0 || pinBytes.length > 16) {
1354             return null;
1355         }
1356         return pinBytes;
1357     }
1358
1359     /**
1360      * Connect to GATT Server hosted by this device. Caller acts as GATT client.
1361      * The callback is used to deliver results to Caller, such as connection status as well
1362      * as any further GATT client operations.
1363      * The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
1364      * GATT client operations.
1365      * @param callback GATT callback handler that will receive asynchronous callbacks.
1366      * @param autoConnect Whether to directly connect to the remote device (false)
1367      *                    or to automatically connect as soon as the remote
1368      *                    device becomes available (true).
1369      * @throws IllegalArgumentException if callback is null
1370      */
1371     public BluetoothGatt connectGatt(Context context, boolean autoConnect,
1372                                      BluetoothGattCallback callback) {
1373         return (connectGatt(context, autoConnect,callback, TRANSPORT_AUTO));
1374     }
1375
1376     /**
1377      * Connect to GATT Server hosted by this device. Caller acts as GATT client.
1378      * The callback is used to deliver results to Caller, such as connection status as well
1379      * as any further GATT client operations.
1380      * The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
1381      * GATT client operations.
1382      * @param callback GATT callback handler that will receive asynchronous callbacks.
1383      * @param autoConnect Whether to directly connect to the remote device (false)
1384      *                    or to automatically connect as soon as the remote
1385      *                    device becomes available (true).
1386      * @param transport preferred transport for GATT connections to remote dual-mode devices
1387      *             {@link BluetoothDevice#TRANSPORT_AUTO} or
1388      *             {@link BluetoothDevice#TRANSPORT_BREDR} or {@link BluetoothDevice#TRANSPORT_LE}
1389      * @throws IllegalArgumentException if callback is null
1390      * @hide
1391      */
1392     public BluetoothGatt connectGatt(Context context, boolean autoConnect,
1393                                      BluetoothGattCallback callback, int transport) {
1394         // TODO(Bluetooth) check whether platform support BLE
1395         //     Do the check here or in GattServer?
1396         BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
1397         IBluetoothManager managerService = adapter.getBluetoothManager();
1398         try {
1399             IBluetoothGatt iGatt = managerService.getBluetoothGatt();
1400             if (iGatt == null) {
1401                 // BLE is not supported
1402                 return null;
1403             }
1404             BluetoothGatt gatt = new BluetoothGatt(context, iGatt, this, transport);
1405             gatt.connect(autoConnect, callback);
1406             return gatt;
1407         } catch (RemoteException e) {Log.e(TAG, "", e);}
1408         return null;
1409     }
1410 }