public final class

BluetoothDevice

extends Object
implements Parcelable
java.lang.Object
   ↳ android.bluetooth.BluetoothDevice

Class Overview

Represents a remote Bluetooth device. A BluetoothDevice lets you create a connection with the repective device or query information about it, such as the name, address, class, and bonding state.

This class is really just a thin wrapper for a Bluetooth hardware address. Objects of this class are immutable. Operations on this class are performed on the remote Bluetooth hardware address, using the BluetoothAdapter that was used to create this BluetoothDevice.

To get a BluetoothDevice, use BluetoothAdapter.getRemoteDevice(String) to create one representing a device of a known MAC address (which you can get through device discovery with BluetoothAdapter) or get one from the set of bonded devices returned by BluetoothAdapter.getBondedDevices(). You can then open a BluetoothSocket for communciation with the remote device, using createRfcommSocketToServiceRecord(UUID).

Note: Requires the BLUETOOTH permission.

See Also

Summary

Constants
String ACTION_ACL_CONNECTED Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device.
String ACTION_ACL_DISCONNECTED Broadcast Action: Indicates a low level (ACL) disconnection from a remote device.
String ACTION_ACL_DISCONNECT_REQUESTED Broadcast Action: Indicates that a low level (ACL) disconnection has been requested for a remote device, and it will soon be disconnected.
String ACTION_BOND_STATE_CHANGED Broadcast Action: Indicates a change in the bond state of a remote device.
String ACTION_CLASS_CHANGED Broadcast Action: Bluetooth class of a remote device has changed.
String ACTION_FOUND Broadcast Action: Remote device discovered.
String ACTION_NAME_CHANGED Broadcast Action: Indicates the friendly name of a remote device has been retrieved for the first time, or changed since the last retrieval.
int BOND_BONDED Indicates the remote device is bonded (paired).
int BOND_BONDING Indicates bonding (pairing) is in progress with the remote device.
int BOND_NONE Indicates the remote device is not bonded (paired).
Creator<BluetoothDevice> CREATOR
int ERROR Sentinel error value for this class.
String EXTRA_BOND_STATE Used as an int extra field in ACTION_BOND_STATE_CHANGED intents.
String EXTRA_CLASS Used as an Parcelable BluetoothClass extra field in ACTION_FOUND and ACTION_CLASS_CHANGED intents.
String EXTRA_DEVICE Used as a Parcelable BluetoothDevice extra field in every intent broadcast by this class.
String EXTRA_NAME Used as a String extra field in ACTION_NAME_CHANGED and ACTION_FOUND intents.
String EXTRA_PREVIOUS_BOND_STATE Used as an int extra field in ACTION_BOND_STATE_CHANGED intents.
String EXTRA_RSSI Used as an optional short extra field in ACTION_FOUND intents.
[Expand]
Inherited Constants
From interface android.os.Parcelable
Public Methods
BluetoothSocket createRfcommSocketToServiceRecord(UUID uuid)
Create an RFCOMM BluetoothSocket ready to start a secure outgoing connection to this remote device using SDP lookup of uuid.
int describeContents()
Describe the kinds of special objects contained in this Parcelable's marshalled representation.
boolean equals(Object o)
Compares this instance with the specified object and indicates if they are equal.
String getAddress()
Returns the hardware address of this BluetoothDevice.
BluetoothClass getBluetoothClass()
Get the Bluetooth class of the remote device.
int getBondState()
Get the bond state of the remote device.
String getName()
Get the friendly Bluetooth name of the remote device.
int hashCode()
Returns an integer hash code for this object.
String toString()
Returns a string representation of this BluetoothDevice.
void writeToParcel(Parcel out, int flags)
Flatten this object in to a Parcel.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.os.Parcelable

Constants

public static final String ACTION_ACL_CONNECTED

Since: API Level 5

Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device.

Always contains the extra field EXTRA_DEVICE.

ACL connections are managed automatically by the Android Bluetooth stack.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_CONNECTED"

public static final String ACTION_ACL_DISCONNECTED

Since: API Level 5

Broadcast Action: Indicates a low level (ACL) disconnection from a remote device.

Always contains the extra field EXTRA_DEVICE.

ACL connections are managed automatically by the Android Bluetooth stack.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_DISCONNECTED"

public static final String ACTION_ACL_DISCONNECT_REQUESTED

Since: API Level 5

Broadcast Action: Indicates that a low level (ACL) disconnection has been requested for a remote device, and it will soon be disconnected.

This is useful for graceful disconnection. Applications should use this intent as a hint to immediately terminate higher level connections (RFCOMM, L2CAP, or profile connections) to the remote device.

Always contains the extra field EXTRA_DEVICE.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED"

public static final String ACTION_BOND_STATE_CHANGED

Since: API Level 5

Broadcast Action: Indicates a change in the bond state of a remote device. For example, if a device is bonded (paired).

Always contains the extra fields EXTRA_DEVICE, EXTRA_BOND_STATE and EXTRA_PREVIOUS_BOND_STATE.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.BOND_STATE_CHANGED"

public static final String ACTION_CLASS_CHANGED

Since: API Level 5

Broadcast Action: Bluetooth class of a remote device has changed.

Always contains the extra fields EXTRA_DEVICE and EXTRA_CLASS.

Requires BLUETOOTH to receive.

See Also
Constant Value: "android.bluetooth.device.action.CLASS_CHANGED"

public static final String ACTION_FOUND

Since: API Level 5

Broadcast Action: Remote device discovered.

Sent when a remote device is found during discovery.

Always contains the extra fields EXTRA_DEVICE and EXTRA_CLASS. Can contain the extra fields EXTRA_NAME and/or EXTRA_RSSI if they are available.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.FOUND"

public static final String ACTION_NAME_CHANGED

Since: API Level 5

Broadcast Action: Indicates the friendly name of a remote device has been retrieved for the first time, or changed since the last retrieval.

Always contains the extra fields EXTRA_DEVICE and EXTRA_NAME.

Requires BLUETOOTH to receive.

Constant Value: "android.bluetooth.device.action.NAME_CHANGED"

public static final int BOND_BONDED

Since: API Level 5

Indicates the remote device is bonded (paired).

A shared link keys exists locally for the remote device, so communication can be authenticated and encrypted.

Being bonded (paired) with a remote device does not necessarily mean the device is currently connected. It just means that the ponding procedure was compeleted at some earlier time, and the link key is still stored locally, ready to use on the next connection.

Constant Value: 12 (0x0000000c)

public static final int BOND_BONDING

Since: API Level 5

Indicates bonding (pairing) is in progress with the remote device.

Constant Value: 11 (0x0000000b)

public static final int BOND_NONE

Since: API Level 5

Indicates the remote device is not bonded (paired).

There is no shared link key with the remote device, so communication (if it is allowed at all) will be unauthenticated and unencrypted.

Constant Value: 10 (0x0000000a)

public static final Creator<BluetoothDevice> CREATOR

Since: API Level 5

public static final int ERROR

Since: API Level 5

Sentinel error value for this class. Guaranteed to not equal any other integer constant in this class. Provided as a convenience for functions that require a sentinel error value, for example:

Intent.getIntExtra(BluetoothDevice.EXTRA_BOND_STATE, BluetoothDevice.ERROR)

Constant Value: -2147483648 (0x80000000)

public static final String EXTRA_BOND_STATE

Since: API Level 5

Used as an int extra field in ACTION_BOND_STATE_CHANGED intents. Contains the bond state of the remote device.

Possible values are: BOND_NONE, BOND_BONDING, BOND_BONDED.

Constant Value: "android.bluetooth.device.extra.BOND_STATE"

public static final String EXTRA_CLASS

Since: API Level 5

Used as an Parcelable BluetoothClass extra field in ACTION_FOUND and ACTION_CLASS_CHANGED intents.

Constant Value: "android.bluetooth.device.extra.CLASS"

public static final String EXTRA_DEVICE

Since: API Level 5

Used as a Parcelable BluetoothDevice extra field in every intent broadcast by this class. It contains the BluetoothDevice that the intent applies to.

Constant Value: "android.bluetooth.device.extra.DEVICE"

public static final String EXTRA_NAME

Since: API Level 5

Used as a String extra field in ACTION_NAME_CHANGED and ACTION_FOUND intents. It contains the friendly Bluetooth name.

Constant Value: "android.bluetooth.device.extra.NAME"

public static final String EXTRA_PREVIOUS_BOND_STATE

Since: API Level 5

Used as an int extra field in ACTION_BOND_STATE_CHANGED intents. Contains the previous bond state of the remote device.

Possible values are: BOND_NONE, BOND_BONDING, BOND_BONDED.

Constant Value: "android.bluetooth.device.extra.PREVIOUS_BOND_STATE"

public static final String EXTRA_RSSI

Since: API Level 5

Used as an optional short extra field in ACTION_FOUND intents. Contains the RSSI value of the remote device as reported by the Bluetooth hardware.

Constant Value: "android.bluetooth.device.extra.RSSI"

Public Methods

public BluetoothSocket createRfcommSocketToServiceRecord (UUID uuid)

Since: API Level 5

Create an RFCOMM BluetoothSocket ready to start a secure outgoing connection to this remote device using SDP lookup of uuid.

This is designed to be used with listenUsingRfcommWithServiceRecord(String, UUID) for peer-peer Bluetooth applications.

Use connect() to intiate the outgoing connection. This will also perform an SDP lookup of the given uuid to determine which channel to connect to.

The remote device will be authenticated and communication on this socket will be encrypted.

Requires BLUETOOTH

Parameters
uuid service record uuid to lookup RFCOMM channel
Returns
  • a RFCOMM BluetoothServerSocket ready for an outgoing connection
Throws
IOException on error, for example Bluetooth not available, or insufficient permissions

public int describeContents ()

Since: API Level 5

Describe the kinds of special objects contained in this Parcelable's marshalled representation.

Returns
  • a bitmask indicating the set of special object types marshalled by the Parcelable.

public boolean equals (Object o)

Since: API Level 5

Compares this instance with the specified object and indicates if they are equal. In order to be equal, o must represent the same object as this instance using a class-specific comparison. The general contract is that this comparison should be both transitive and reflexive.

The implementation in Object returns true only if o is the exact same object as the receiver (using the == operator for comparison). Subclasses often implement equals(Object) so that it takes into account the two object's types and states.

The general contract for the equals(Object) and hashCode() methods is that if equals returns true for any two objects, then hashCode() must return the same value for these objects. This means that subclasses of Object usually override either both methods or none of them.

Parameters
o the object to compare this instance with.
Returns
  • true if the specified object is equal to this Object; false otherwise.

public String getAddress ()

Since: API Level 5

Returns the hardware address of this BluetoothDevice.

For example, "00:11:22:AA:BB:CC".

Returns
  • Bluetooth hardware address as string

public BluetoothClass getBluetoothClass ()

Since: API Level 5

Get the Bluetooth class of the remote device.

Requires BLUETOOTH.

Returns
  • Bluetooth class object, or null on error

public int getBondState ()

Since: API Level 5

Get the bond state of the remote device.

Possible values for the bond state are: BOND_NONE, BOND_BONDING, BOND_BONDED.

Requires BLUETOOTH.

Returns
  • the bond state

public String getName ()

Since: API Level 5

Get the friendly Bluetooth name of the remote device.

The local adapter will automatically retrieve remote names when performing a device scan, and will cache them. This method just returns the name for this device from the cache.

Requires BLUETOOTH

Returns
  • the Bluetooth name, or null if there was a problem.

public int hashCode ()

Since: API Level 5

Returns an integer hash code for this object. By contract, any two objects for which equals(Object) returns true must return the same hash code value. This means that subclasses of Object usually override both methods or neither method.

Returns
  • this object's hash code.

public String toString ()

Since: API Level 5

Returns a string representation of this BluetoothDevice.

Currently this is the Bluetooth hardware address, for example "00:11:22:AA:BB:CC". However, you should always use getAddress() if you explicitly require the Bluetooth hardware address in case the toString() representation changes in the future.

Returns
  • string representation of this BluetoothDevice

public void writeToParcel (Parcel out, int flags)

Since: API Level 5

Flatten this object in to a Parcel.

Parameters
out The Parcel in which the object should be written.
flags Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE.