# Print output for @column tags ?>
public
final
class
BluetoothDevice
extends Object
implements
Parcelable
java.lang.Object | |
↳ | android.bluetooth.BluetoothDevice |
Represents a remote Bluetooth device. A BluetoothDevice
lets you
create a connection with the respective 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 communication with the remote device, using
createRfcommSocketToServiceRecord(java.util.UUID)
over Bluetooth BR/EDR or using
createL2capChannel(int)
over Bluetooth LE.
For more information about using Bluetooth, read the Bluetooth developer guide.
See also:
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_ALIAS_CHANGED
Broadcast Action: Indicates the alias of a remote device has been changed. |
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. |
String |
ACTION_PAIRING_REQUEST
Broadcast Action: This intent is used to broadcast PAIRING REQUEST
|
String |
ACTION_UUID
Broadcast Action: This intent is used to broadcast the |
int |
ADDRESS_TYPE_PUBLIC
Hardware MAC Address of the device |
int |
ADDRESS_TYPE_RANDOM
Address is either resolvable, non-resolvable or static. |
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). |
int |
DEVICE_TYPE_CLASSIC
Bluetooth device type, Classic - BR/EDR devices |
int |
DEVICE_TYPE_DUAL
Bluetooth device type, Dual Mode - BR/EDR/LE |
int |
DEVICE_TYPE_LE
Bluetooth device type, Low Energy - LE-only |
int |
DEVICE_TYPE_UNKNOWN
Bluetooth device type, Unknown |
int |
ERROR
Sentinel error value for this class. |
String |
EXTRA_BOND_STATE
Used as an int extra field in |
String |
EXTRA_CLASS
Used as a Parcelable |
String |
EXTRA_DEVICE
Used as a Parcelable |
String |
EXTRA_NAME
Used as a String extra field in |
String |
EXTRA_PAIRING_KEY
Used as an int extra field in |
String |
EXTRA_PAIRING_VARIANT
Used as an int extra field in |
String |
EXTRA_PREVIOUS_BOND_STATE
Used as an int extra field in |
String |
EXTRA_RSSI
Used as an optional short extra field in |
String |
EXTRA_UUID
Used as an extra field in |
int |
PAIRING_VARIANT_PASSKEY_CONFIRMATION
The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user. |
int |
PAIRING_VARIANT_PIN
The user will be prompted to enter a pin or an app will enter a pin for user. |
int |
PHY_LE_1M
Bluetooth LE 1M PHY. |
int |
PHY_LE_1M_MASK
Bluetooth LE 1M PHY mask. |
int |
PHY_LE_2M
Bluetooth LE 2M PHY. |
int |
PHY_LE_2M_MASK
Bluetooth LE 2M PHY mask. |
int |
PHY_LE_CODED
Bluetooth LE Coded PHY. |
int |
PHY_LE_CODED_MASK
Bluetooth LE Coded PHY mask. |
int |
PHY_OPTION_NO_PREFERRED
No preferred coding when transmitting on the LE Coded PHY. |
int |
PHY_OPTION_S2
Prefer the S=2 coding to be used when transmitting on the LE Coded PHY. |
int |
PHY_OPTION_S8
Prefer the S=8 coding to be used when transmitting on the LE Coded PHY. |
int |
TRANSPORT_AUTO
No preference of physical transport for GATT connections to remote dual-mode devices |
int |
TRANSPORT_BREDR
Prefer BR/EDR transport for GATT connections to remote dual-mode devices |
int |
TRANSPORT_LE
Prefer LE transport for GATT connections to remote dual-mode devices |
Inherited constants |
---|
Fields | |
---|---|
public
static
final
Creator<BluetoothDevice> |
CREATOR
|
Public methods | |
---|---|
BluetoothGatt
|
connectGatt(Context context, boolean autoConnect, BluetoothGattCallback callback)
Connect to GATT Server hosted by this device. |
BluetoothGatt
|
connectGatt(Context context, boolean autoConnect, BluetoothGattCallback callback, int transport, int phy, Handler handler)
Connect to GATT Server hosted by this device. |
BluetoothGatt
|
connectGatt(Context context, boolean autoConnect, BluetoothGattCallback callback, int transport, int phy)
Connect to GATT Server hosted by this device. |
BluetoothGatt
|
connectGatt(Context context, boolean autoConnect, BluetoothGattCallback callback, int transport)
Connect to GATT Server hosted by this device. |
boolean
|
createBond()
Start the bonding (pairing) process with the remote device. |
BluetoothSocket
|
createInsecureL2capChannel(int psm)
Create a Bluetooth L2CAP Connection-oriented Channel (CoC) |
BluetoothSocket
|
createInsecureRfcommSocketToServiceRecord(UUID uuid)
Create an RFCOMM |
BluetoothSocket
|
createL2capChannel(int psm)
Create a Bluetooth L2CAP Connection-oriented Channel (CoC) |
BluetoothSocket
|
createRfcommSocketToServiceRecord(UUID uuid)
Create an RFCOMM |
int
|
describeContents()
Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. |
boolean
|
equals(Object o)
Indicates whether some other object is "equal to" this one. |
boolean
|
fetchUuidsWithSdp()
Perform a service discovery on the remote device to get the UUIDs supported. |
String
|
getAddress()
Returns the hardware address of this BluetoothDevice. |
String
|
getAlias()
Get the locally modifiable name (alias) of the remote Bluetooth device. |
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
|
getType()
Get the Bluetooth device type of the remote device. |
ParcelUuid[]
|
getUuids()
Returns the supported features (UUIDs) of the remote device. |
int
|
hashCode()
Returns a hash code value for the object. |
int
|
setAlias(String alias)
Sets the locally modifiable name (alias) of the remote Bluetooth device. |
boolean
|
setPairingConfirmation(boolean confirm)
Confirm passkey for |
boolean
|
setPin(byte[] pin)
Set the pin during pairing when the pairing method is |
String
|
toString()
Returns a string representation of this BluetoothDevice. |
void
|
writeToParcel(Parcel out, int flags)
Flatten this object in to a Parcel. |
Inherited methods | |
---|---|
public static final String ACTION_ACL_CONNECTED
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.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.ACL_CONNECTED"
public static final String ACTION_ACL_DISCONNECTED
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.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.ACL_DISCONNECTED"
public static final 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.
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
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED"
public static final String ACTION_ALIAS_CHANGED
Broadcast Action: Indicates the alias of a remote device has been changed.
Always contains the extra field EXTRA_DEVICE
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.ALIAS_CHANGED"
public static final String ACTION_BOND_STATE_CHANGED
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
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.BOND_STATE_CHANGED"
public static final String ACTION_CLASS_CHANGED
Broadcast Action: Bluetooth class of a remote device has changed.
Always contains the extra fields EXTRA_DEVICE
and EXTRA_CLASS
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
See also:
Constant Value: "android.bluetooth.device.action.CLASS_CHANGED"
public static final String ACTION_FOUND
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.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_SCAN
permission which can be gained with
Activity.requestPermissions(String[], int)
.
In addition, this requires either the
Manifest.permission#ACCESS_FINE_LOCATION
permission or a strong assertion that you will never derive the
physical location of the device. You can make this assertion by
declaring usesPermissionFlags="neverForLocation"
on the
relevant <uses-permission>
manifest tag, but it may
restrict the types of Bluetooth devices you can interact with.
Requires Manifest.permission.BLUETOOTH_SCAN
Constant Value: "android.bluetooth.device.action.FOUND"
public static final 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.
Always contains the extra fields EXTRA_DEVICE
and EXTRA_NAME
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.NAME_CHANGED"
public static final String ACTION_PAIRING_REQUEST
Broadcast Action: This intent is used to broadcast PAIRING REQUEST
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH_ADMIN
permission which can be gained with a simple
<uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.PAIRING_REQUEST"
public static final String ACTION_UUID
Broadcast Action: This intent is used to broadcast the UUID
wrapped as a ParcelUuid
of the remote device after it
has been fetched. This intent is sent only when the UUIDs of the remote
device are requested to be fetched using Service Discovery Protocol
Always contains the extra field EXTRA_DEVICE
Always contains the extra field EXTRA_UUID
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH_ADMIN
permission which can be gained with a simple
<uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Constant Value: "android.bluetooth.device.action.UUID"
public static final int ADDRESS_TYPE_PUBLIC
Hardware MAC Address of the device
Constant Value: 0 (0x00000000)
public static final int ADDRESS_TYPE_RANDOM
Address is either resolvable, non-resolvable or static.
Constant Value: 1 (0x00000001)
public static final int BOND_BONDED
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 pending procedure was completed 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
Indicates bonding (pairing) is in progress with the remote device.
Constant Value: 11 (0x0000000b)
public static final int BOND_NONE
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 int DEVICE_TYPE_CLASSIC
Bluetooth device type, Classic - BR/EDR devices
Constant Value: 1 (0x00000001)
public static final int DEVICE_TYPE_DUAL
Bluetooth device type, Dual Mode - BR/EDR/LE
Constant Value: 3 (0x00000003)
public static final int DEVICE_TYPE_LE
Bluetooth device type, Low Energy - LE-only
Constant Value: 2 (0x00000002)
public static final int DEVICE_TYPE_UNKNOWN
Bluetooth device type, Unknown
Constant Value: 0 (0x00000000)
public static final int ERROR
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
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
Used as a 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
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
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_PAIRING_KEY
Used as an int extra field in ACTION_PAIRING_REQUEST
intents as the value of passkey.
Constant Value: "android.bluetooth.device.extra.PAIRING_KEY"
public static final String EXTRA_PAIRING_VARIANT
Used as an int extra field in ACTION_PAIRING_REQUEST
intents to indicate pairing method used. Possible values are:
PAIRING_VARIANT_PIN
,
PAIRING_VARIANT_PASSKEY_CONFIRMATION
,
Constant Value: "android.bluetooth.device.extra.PAIRING_VARIANT"
public static final String EXTRA_PREVIOUS_BOND_STATE
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
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 static final String EXTRA_UUID
Used as an extra field in ACTION_UUID
intents,
Contains the ParcelUuid
s of the remote device which
is a parcelable version of UUID
.
Constant Value: "android.bluetooth.device.extra.UUID"
public static final int PAIRING_VARIANT_PASSKEY_CONFIRMATION
The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user.
Constant Value: 2 (0x00000002)
public static final int PAIRING_VARIANT_PIN
The user will be prompted to enter a pin or an app will enter a pin for user.
Constant Value: 0 (0x00000000)
public static final int PHY_LE_1M
Bluetooth LE 1M PHY. Used to refer to LE 1M Physical Channel for advertising, scanning or connection.
Constant Value: 1 (0x00000001)
public static final int PHY_LE_1M_MASK
Bluetooth LE 1M PHY mask. Used to specify LE 1M Physical Channel as one of many available options in a bitmask.
Constant Value: 1 (0x00000001)
public static final int PHY_LE_2M
Bluetooth LE 2M PHY. Used to refer to LE 2M Physical Channel for advertising, scanning or connection.
Constant Value: 2 (0x00000002)
public static final int PHY_LE_2M_MASK
Bluetooth LE 2M PHY mask. Used to specify LE 2M Physical Channel as one of many available options in a bitmask.
Constant Value: 2 (0x00000002)
public static final int PHY_LE_CODED
Bluetooth LE Coded PHY. Used to refer to LE Coded Physical Channel for advertising, scanning or connection.
Constant Value: 3 (0x00000003)
public static final int PHY_LE_CODED_MASK
Bluetooth LE Coded PHY mask. Used to specify LE Coded Physical Channel as one of many available options in a bitmask.
Constant Value: 4 (0x00000004)
public static final int PHY_OPTION_NO_PREFERRED
No preferred coding when transmitting on the LE Coded PHY.
Constant Value: 0 (0x00000000)
public static final int PHY_OPTION_S2
Prefer the S=2 coding to be used when transmitting on the LE Coded PHY.
Constant Value: 1 (0x00000001)
public static final int PHY_OPTION_S8
Prefer the S=8 coding to be used when transmitting on the LE Coded PHY.
Constant Value: 2 (0x00000002)
public static final int TRANSPORT_AUTO
No preference of physical transport for GATT connections to remote dual-mode devices
Constant Value: 0 (0x00000000)
public static final int TRANSPORT_BREDR
Prefer BR/EDR transport for GATT connections to remote dual-mode devices
Constant Value: 1 (0x00000001)
public static final int TRANSPORT_LE
Prefer LE transport for GATT connections to remote dual-mode devices
Constant Value: 2 (0x00000002)
public BluetoothGatt connectGatt (Context context, boolean autoConnect, BluetoothGattCallback callback)
Connect to GATT Server hosted by this device. Caller acts as GATT client.
The callback is used to deliver results to Caller, such as connection status as well
as any further GATT client operations.
The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
GATT client operations.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
context |
Context |
autoConnect |
boolean : Whether to directly connect to the remote device (false) or to
automatically connect as soon as the remote device becomes available (true). |
callback |
BluetoothGattCallback : GATT callback handler that will receive asynchronous callbacks. |
Returns | |
---|---|
BluetoothGatt |
Throws | |
---|---|
IllegalArgumentException |
if callback is null |
public BluetoothGatt connectGatt (Context context, boolean autoConnect, BluetoothGattCallback callback, int transport, int phy, Handler handler)
Connect to GATT Server hosted by this device. Caller acts as GATT client.
The callback is used to deliver results to Caller, such as connection status as well
as any further GATT client operations.
The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
GATT client operations.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
context |
Context |
autoConnect |
boolean : Whether to directly connect to the remote device (false) or to
automatically connect as soon as the remote device becomes available (true). |
callback |
BluetoothGattCallback : GATT callback handler that will receive asynchronous callbacks. |
transport |
int : preferred transport for GATT connections to remote dual-mode devices TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or TRANSPORT_LE |
phy |
int : preferred PHY for connections to remote LE device. Bitwise OR of any of PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , an dPHY_LE_CODED_MASK . This option does not take effect if autoConnect
is set to true. |
handler |
Handler : The handler to use for the callback. If null , callbacks will happen on
an un-specified background thread. |
Returns | |
---|---|
BluetoothGatt |
Throws | |
---|---|
NullPointerException |
if callback is null |
public BluetoothGatt connectGatt (Context context, boolean autoConnect, BluetoothGattCallback callback, int transport, int phy)
Connect to GATT Server hosted by this device. Caller acts as GATT client.
The callback is used to deliver results to Caller, such as connection status as well
as any further GATT client operations.
The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
GATT client operations.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
context |
Context |
autoConnect |
boolean : Whether to directly connect to the remote device (false) or to
automatically connect as soon as the remote device becomes available (true). |
callback |
BluetoothGattCallback : GATT callback handler that will receive asynchronous callbacks. |
transport |
int : preferred transport for GATT connections to remote dual-mode devices TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or TRANSPORT_LE |
phy |
int : preferred PHY for connections to remote LE device. Bitwise OR of any of PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , and PHY_LE_CODED_MASK . This option does not take effect if autoConnect
is set to true. |
Returns | |
---|---|
BluetoothGatt |
Throws | |
---|---|
NullPointerException |
if callback is null |
public BluetoothGatt connectGatt (Context context, boolean autoConnect, BluetoothGattCallback callback, int transport)
Connect to GATT Server hosted by this device. Caller acts as GATT client.
The callback is used to deliver results to Caller, such as connection status as well
as any further GATT client operations.
The method returns a BluetoothGatt instance. You can use BluetoothGatt to conduct
GATT client operations.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
context |
Context |
autoConnect |
boolean : Whether to directly connect to the remote device (false) or to
automatically connect as soon as the remote device becomes available (true). |
callback |
BluetoothGattCallback : GATT callback handler that will receive asynchronous callbacks. |
transport |
int : preferred transport for GATT connections to remote dual-mode devices TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or TRANSPORT_LE |
Returns | |
---|---|
BluetoothGatt |
Throws | |
---|---|
IllegalArgumentException |
if callback is null |
public boolean createBond ()
Start the bonding (pairing) process with the remote device.
This is an asynchronous call, it will return immediately. Register
for ACTION_BOND_STATE_CHANGED
intents to be notified when
the bonding process completes, and its result.
Android system services will handle the necessary user interactions
to confirm and complete the bonding process.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH_ADMIN
permission which can be gained with a simple
<uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
false on immediate error, true if bonding will begin |
public BluetoothSocket createInsecureL2capChannel (int psm)
Create a Bluetooth L2CAP Connection-oriented Channel (CoC) BluetoothSocket
that can
be used to start a secure outgoing connection to the remote device with the same dynamic
protocol/service multiplexer (PSM) value. The supported Bluetooth transport is LE only.
This is designed to be used with BluetoothAdapter.listenUsingInsecureL2capChannel()
for peer-peer Bluetooth applications.
Use BluetoothSocket#connect
to initiate the outgoing connection.
Application using this API is responsible for obtaining PSM value from remote device.
The communication channel may not have an authenticated link key, i.e. it may be subject
to person-in-the-middle attacks. Use createL2capChannel(int)
if an encrypted and
authenticated communication channel is possible.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
psm |
int : dynamic PSM value from remote device |
Returns | |
---|---|
BluetoothSocket |
a CoC #BluetoothSocket ready for an outgoing connection
This value cannot be null . |
Throws | |
---|---|
IOException |
on error, for example Bluetooth not available, or insufficient permissions |
public BluetoothSocket createInsecureRfcommSocketToServiceRecord (UUID uuid)
Create an RFCOMM BluetoothSocket
socket ready to start an insecure
outgoing connection to this remote device using SDP lookup of uuid.
The communication channel will not have an authenticated link key
i.e it will be subject to person-in-the-middle attacks. For Bluetooth 2.1
devices, the link key will be encrypted, as encryption is mandatory.
For legacy devices (pre Bluetooth 2.1 devices) the link key will
be not be encrypted. Use createRfcommSocketToServiceRecord(UUID)
if an
encrypted and authenticated communication channel is desired.
This is designed to be used with BluetoothAdapter.listenUsingInsecureRfcommWithServiceRecord(String, UUID)
for peer-peer
Bluetooth applications.
Use BluetoothSocket#connect
to initiate 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.
Hint: If you are connecting to a Bluetooth serial board then try
using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.
However if you are connecting to an Android peer then please generate
your own unique UUID.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
uuid |
UUID : service record uuid to lookup RFCOMM channel |
Returns | |
---|---|
BluetoothSocket |
a RFCOMM BluetoothServerSocket ready for an outgoing connection |
Throws | |
---|---|
IOException |
on error, for example Bluetooth not available, or insufficient permissions |
public BluetoothSocket createL2capChannel (int psm)
Create a Bluetooth L2CAP Connection-oriented Channel (CoC) BluetoothSocket
that can
be used to start a secure outgoing connection to the remote device with the same dynamic
protocol/service multiplexer (PSM) value. The supported Bluetooth transport is LE only.
This is designed to be used with BluetoothAdapter#listenUsingL2capChannel()
for
peer-peer Bluetooth applications.
Use BluetoothSocket#connect
to initiate the outgoing connection.
Application using this API is responsible for obtaining PSM value from remote device.
The remote device will be authenticated and communication on this socket will be encrypted.
Use this socket if an authenticated socket link is possible. Authentication refers
to the authentication of the link key to prevent person-in-the-middle type of attacks.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
psm |
int : dynamic PSM value from remote device |
Returns | |
---|---|
BluetoothSocket |
a CoC #BluetoothSocket ready for an outgoing connection
This value cannot be null . |
Throws | |
---|---|
IOException |
on error, for example Bluetooth not available, or insufficient permissions |
public BluetoothSocket createRfcommSocketToServiceRecord (UUID uuid)
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 BluetoothAdapter.listenUsingRfcommWithServiceRecord(String, UUID)
for peer-peer
Bluetooth applications.
Use BluetoothSocket#connect
to initiate 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.
Use this socket only if an authenticated socket link is possible.
Authentication refers to the authentication of the link key to
prevent person-in-the-middle type of attacks.
For example, for Bluetooth 2.1 devices, if any of the devices does not
have an input and output capability or just has the ability to
display a numeric key, a secure socket connection is not possible.
In such a case, use createInsecureRfcommSocketToServiceRecord(UUID)
.
For more details, refer to the Security Model section 5.2 (vol 3) of
Bluetooth Core Specification version 2.1 + EDR.
Hint: If you are connecting to a Bluetooth serial board then try
using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.
However if you are connecting to an Android peer then please generate
your own unique UUID.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
uuid |
UUID : service record uuid to lookup RFCOMM channel |
Returns | |
---|---|
BluetoothSocket |
a RFCOMM BluetoothServerSocket ready for an outgoing connection |
Throws | |
---|---|
IOException |
on error, for example Bluetooth not available, or insufficient permissions |
public int describeContents ()
Describe the kinds of special objects contained in this Parcelable
instance's marshaled representation. For example, if the object will
include a file descriptor in the output of writeToParcel(android.os.Parcel, int)
,
the return value of this method must include the
CONTENTS_FILE_DESCRIPTOR
bit.
Returns | |
---|---|
int |
a bitmask indicating the set of special object types marshaled
by this Parcelable object instance.
Value is either 0 or CONTENTS_FILE_DESCRIPTOR |
public boolean equals (Object o)
Indicates whether some other object is "equal to" this one.
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y)
consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals
method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode
method whenever this method is overridden, so as to maintain the
general contract for the hashCode
method, which states
that equal objects must have equal hash codes.
Parameters | |
---|---|
o |
Object : This value may be null . |
Returns | |
---|---|
boolean |
true if this object is the same as the obj
argument; false otherwise. |
public boolean fetchUuidsWithSdp ()
Perform a service discovery on the remote device to get the UUIDs supported.
This API is asynchronous and ACTION_UUID
intent is sent,
with the UUIDs supported by the remote end. If there is an error
in getting the SDP records or if the process takes a long time, or the device is bonding and
we have its UUIDs cached, ACTION_UUID
intent is sent with the UUIDs that is
currently present in the cache. Clients should use the getUuids()
to get UUIDs
if service discovery is not to be performed. If there is an ongoing bonding process,
service discovery or device inquiry, the request will be queued.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
False if the check fails, True if the process of initiating an ACL connection to the remote device was started or cached UUIDs will be broadcast. |
public String getAddress ()
Returns the hardware address of this BluetoothDevice.
For example, "00:11:22:AA:BB:CC".
Returns | |
---|---|
String |
Bluetooth hardware address as string |
public String getAlias ()
Get the locally modifiable name (alias) of the remote Bluetooth device.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
String |
the Bluetooth alias, the friendly device name if no alias, or null if there was a problem |
public BluetoothClass getBluetoothClass ()
Get the Bluetooth class of the remote device.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
BluetoothClass |
Bluetooth class object, or null on error |
public int getBondState ()
Get the bond state of the remote device.
Possible values for the bond state are:
BOND_NONE
,
BOND_BONDING
,
BOND_BONDED
.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
int |
the bond state |
public String getName ()
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.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
String |
the Bluetooth name, or null if there was a problem. |
public int getType ()
Get the Bluetooth device type of the remote device.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
int |
the device type DEVICE_TYPE_CLASSIC , DEVICE_TYPE_LE DEVICE_TYPE_DUAL . DEVICE_TYPE_UNKNOWN if it's not available |
public ParcelUuid[] getUuids ()
Returns the supported features (UUIDs) of the remote device.
This method does not start a service discovery procedure to retrieve the UUIDs from the remote device. Instead, the local cached copy of the service UUIDs are returned.
Use fetchUuidsWithSdp()
if fresh UUIDs are desired.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
ParcelUuid[] |
the supported features (UUIDs) of the remote device, or null on error |
public int hashCode ()
Returns a hash code value for the object. This method is
supported for the benefit of hash tables such as those provided by
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
Returns | |
---|---|
int |
a hash code value for this object. |
public int setAlias (String alias)
Sets the locally modifiable name (alias) of the remote Bluetooth device. This method overwrites the previously stored alias. The new alias is saved in local storage so that the change is preserved over power cycles.
This method requires the calling app to be associated with Companion Device Manager (see
CompanionDeviceManager.associate(AssociationRequest, android.companion.CompanionDeviceManager.Callback, Handler)
) and have the
Manifest.permission.BLUETOOTH_CONNECT
permission. Alternatively, if the
caller has the Manifest.permission.BLUETOOTH_PRIVILEGED
permission, they can
bypass the Companion Device Manager association requirement as well as other permission
requirements.
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH
permission
which can be gained with a simple <uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
alias |
String : is the new locally modifiable name for the remote Bluetooth device which must
be the empty string. If null, we clear the alias.
This value may be null . |
Returns | |
---|---|
int |
whether the alias was successfully changed
Value is BluetoothStatusCodes.SUCCESS , BluetoothStatusCodes.ERROR_BLUETOOTH_NOT_ENABLED , BluetoothStatusCodes.ERROR_BLUETOOTH_NOT_ALLOWED , BluetoothStatusCodes.ERROR_MISSING_BLUETOOTH_CONNECT_PERMISSION , or BluetoothStatusCodes.ERROR_DEVICE_NOT_BONDED |
Throws | |
---|---|
IllegalArgumentException |
if the alias is the empty string |
public boolean setPairingConfirmation (boolean confirm)
Confirm passkey for PAIRING_VARIANT_PASSKEY_CONFIRMATION
pairing.
Requires Manifest.permission.BLUETOOTH_CONNECT
and Manifest.permission.BLUETOOTH_PRIVILEGED
Parameters | |
---|---|
confirm |
boolean |
Returns | |
---|---|
boolean |
true confirmation has been sent out false for error |
public boolean setPin (byte[] pin)
Set the pin during pairing when the pairing method is PAIRING_VARIANT_PIN
For apps targeting Build.VERSION_CODES#R
or lower, this
requires the Manifest.permission#BLUETOOTH_ADMIN
permission which can be gained with a simple
<uses-permission>
manifest tag.
For apps targeting Build.VERSION_CODES#S
or or higher,
this requires the Manifest.permission#BLUETOOTH_CONNECT
permission which can be gained with
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
pin |
byte |
Returns | |
---|---|
boolean |
true pin has been set false for error |
public String toString ()
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 |
string representation of this BluetoothDevice |
public void writeToParcel (Parcel out, int flags)
Flatten this object in to a Parcel.
Parameters | |
---|---|
out |
Parcel : The Parcel in which the object should be written. |
flags |
int : Additional flags about how the object should be written.
May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE .
Value is either 0 or a combination of Parcelable.PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |