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