BluetoothDevice
class BluetoothDevice : Parcelable
kotlin.Any | |
↳ | 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.
Summary
Constants | |
---|---|
static String |
Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device. |
static String |
Broadcast Action: Indicates a low level (ACL) disconnection from a remote device. |
static String |
Broadcast Action: Indicates that a low level (ACL) disconnection has been requested for a remote device, and it will soon be disconnected. |
static String |
Broadcast Action: Indicates the alias of a remote device has been changed. |
static String |
Broadcast Action: Indicates a change in the bond state of a remote device. |
static String |
Broadcast Action: Bluetooth class of a remote device has changed. |
static String |
Broadcast Action: Remote device discovered. |
static String |
Broadcast Action: Indicates the friendly name of a remote device has been retrieved for the first time, or changed since the last retrieval. |
static String |
Broadcast Action: This intent is used to broadcast PAIRING REQUEST |
static String |
Broadcast Action: This intent is used to broadcast the |
static Int |
Address type used to indicate an anonymous advertisement. |
static Int |
Hardware MAC Address of the device |
static Int |
Address is either resolvable, non-resolvable or static. |
static Int |
Address type is unknown or unavailable |
static Int |
Indicates the remote device is bonded (paired). |
static Int |
Indicates bonding (pairing) is in progress with the remote device. |
static Int |
Indicates the remote device is not bonded (paired). |
static Int |
Bluetooth device type, Classic - BR/EDR devices |
static Int |
Bluetooth device type, Dual Mode - BR/EDR/LE |
static Int |
Bluetooth device type, Low Energy - LE-only |
static Int |
Bluetooth device type, Unknown |
static Int |
Sentinel error value for this class. |
static String |
Used as an int extra field in |
static String |
Used as a Parcelable |
static String |
Used as a Parcelable |
static String |
Used as a boolean extra field in |
static String |
Used as a String extra field in |
static String |
Used as an int extra field in |
static String |
Used as an int extra field in |
static String |
Used as an int extra field in |
static String |
Used as an optional short extra field in |
static String |
Used as an int extra field in |
static String |
Used as an extra field in |
static Int |
The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user. |
static Int |
The user will be prompted to enter a pin or an app will enter a pin for user. |
static Int |
Bluetooth LE 1M PHY. |
static Int |
Bluetooth LE 1M PHY mask. |
static Int |
Bluetooth LE 2M PHY. |
static Int |
Bluetooth LE 2M PHY mask. |
static Int |
Bluetooth LE Coded PHY. |
static Int |
Bluetooth LE Coded PHY mask. |
static Int |
No preferred coding when transmitting on the LE Coded PHY. |
static Int |
Prefer the S=2 coding to be used when transmitting on the LE Coded PHY. |
static Int |
Prefer the S=8 coding to be used when transmitting on the LE Coded PHY. |
static Int |
No preference of physical transport for GATT connections to remote dual-mode devices |
static Int |
Constant representing the BR/EDR transport. |
static Int |
Constant representing the Bluetooth Low Energy (BLE) Transport. |
Inherited constants | |
---|---|
Public methods | |
---|---|
BluetoothGatt! |
connectGatt(context: Context!, autoConnect: Boolean, callback: BluetoothGattCallback!) Connect to GATT Server hosted by this device. |
BluetoothGatt! |
connectGatt(context: Context!, autoConnect: Boolean, callback: BluetoothGattCallback!, transport: Int) Connect to GATT Server hosted by this device. |
BluetoothGatt! |
connectGatt(context: Context!, autoConnect: Boolean, callback: BluetoothGattCallback!, transport: Int, phy: Int) Connect to GATT Server hosted by this device. |
BluetoothGatt! |
connectGatt(context: Context!, autoConnect: Boolean, callback: BluetoothGattCallback!, transport: Int, phy: Int, handler: Handler!) Connect to GATT Server hosted by this device. |
Boolean |
Start the bonding (pairing) process with the remote device. |
BluetoothSocket |
Create a Bluetooth L2CAP Connection-oriented Channel (CoC) |
BluetoothSocket! |
Create an RFCOMM |
BluetoothSocket |
createL2capChannel(psm: Int) Create a Bluetooth L2CAP Connection-oriented Channel (CoC) |
BluetoothSocket! |
Create an RFCOMM |
Int | |
Boolean |
Indicates whether some other object is "equal to" this one. |
Boolean |
Perform a service discovery on the remote device to get the UUIDs supported. |
String! |
Returns the hardware address of this BluetoothDevice. |
Int |
Returns the address type of this BluetoothDevice, one of ADDRESS_TYPE_PUBLIC, , ADDRESS_TYPE_ANONYMOUS, or ADDRESS_TYPE_UNKNOWN. |
String? |
getAlias() Get the locally modifiable name (alias) of the remote Bluetooth device. |
BluetoothClass! |
Get the Bluetooth class of the remote device. |
Int |
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. |
Array<ParcelUuid!>! |
getUuids() Returns the supported features (UUIDs) of the remote device. |
Int |
hashCode() |
Int |
Sets the locally modifiable name (alias) of the remote Bluetooth device. |
Boolean |
setPairingConfirmation(confirm: Boolean) Confirm passkey for |
Boolean |
Set the pin during pairing when the pairing method is |
String |
toString() Returns a string representation of this BluetoothDevice. |
Unit |
writeToParcel(out: Parcel, flags: Int) |
Properties | |
---|---|
static Parcelable.Creator<BluetoothDevice!> |
Constants
ACTION_ACL_CONNECTED
static val ACTION_ACL_CONNECTED: String
Broadcast Action: Indicates a low level (ACL) connection has been established with a remote device.
Always contains the extra fields EXTRA_DEVICE
and EXTRA_TRANSPORT
.
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.ACL_CONNECTED"
ACTION_ACL_DISCONNECTED
static val ACTION_ACL_DISCONNECTED: String
Broadcast Action: Indicates a low level (ACL) disconnection from a remote device.
Always contains the extra fields EXTRA_DEVICE
and EXTRA_TRANSPORT
.
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.ACL_DISCONNECTED"
ACTION_ACL_DISCONNECT_REQUESTED
static val ACTION_ACL_DISCONNECT_REQUESTED: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.ACL_DISCONNECT_REQUESTED"
ACTION_ALIAS_CHANGED
static val ACTION_ALIAS_CHANGED: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.ALIAS_CHANGED"
ACTION_BOND_STATE_CHANGED
static val ACTION_BOND_STATE_CHANGED: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.BOND_STATE_CHANGED"
ACTION_CLASS_CHANGED
static val ACTION_CLASS_CHANGED: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.CLASS_CHANGED"
See Also
ACTION_FOUND
static val ACTION_FOUND: String
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
and/or EXTRA_IS_COORDINATED_SET_MEMBER
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 android.app.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 android.Manifest.permission#BLUETOOTH_SCAN
Value: "android.bluetooth.device.action.FOUND"
ACTION_NAME_CHANGED
static val ACTION_NAME_CHANGED: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.NAME_CHANGED"
ACTION_PAIRING_REQUEST
static val ACTION_PAIRING_REQUEST: String
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.PAIRING_REQUEST"
ACTION_UUID
static val ACTION_UUID: String
Broadcast Action: This intent is used to broadcast the UUID
wrapped as a 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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Value: "android.bluetooth.device.action.UUID"
ADDRESS_TYPE_ANONYMOUS
static val ADDRESS_TYPE_ANONYMOUS: Int
Address type used to indicate an anonymous advertisement.
Value: 255
ADDRESS_TYPE_PUBLIC
static val ADDRESS_TYPE_PUBLIC: Int
Hardware MAC Address of the device
Value: 0
ADDRESS_TYPE_RANDOM
static val ADDRESS_TYPE_RANDOM: Int
Address is either resolvable, non-resolvable or static.
Value: 1
ADDRESS_TYPE_UNKNOWN
static val ADDRESS_TYPE_UNKNOWN: Int
Address type is unknown or unavailable
Value: 65535
BOND_BONDED
static val BOND_BONDED: Int
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.
Value: 12
BOND_BONDING
static val BOND_BONDING: Int
Indicates bonding (pairing) is in progress with the remote device.
Value: 11
BOND_NONE
static val BOND_NONE: Int
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.
Value: 10
DEVICE_TYPE_CLASSIC
static val DEVICE_TYPE_CLASSIC: Int
Bluetooth device type, Classic - BR/EDR devices
Value: 1
DEVICE_TYPE_DUAL
static val DEVICE_TYPE_DUAL: Int
Bluetooth device type, Dual Mode - BR/EDR/LE
Value: 3
DEVICE_TYPE_LE
static val DEVICE_TYPE_LE: Int
Bluetooth device type, Low Energy - LE-only
Value: 2
DEVICE_TYPE_UNKNOWN
static val DEVICE_TYPE_UNKNOWN: Int
Bluetooth device type, Unknown
Value: 0
ERROR
static val ERROR: Int
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)
Value: -2147483648
EXTRA_BOND_STATE
static val EXTRA_BOND_STATE: String
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
.
Value: "android.bluetooth.device.extra.BOND_STATE"
EXTRA_CLASS
static val EXTRA_CLASS: String
Used as a Parcelable BluetoothClass
extra field in ACTION_FOUND
and ACTION_CLASS_CHANGED
intents.
Value: "android.bluetooth.device.extra.CLASS"
EXTRA_DEVICE
static val EXTRA_DEVICE: String
Used as a Parcelable BluetoothDevice
extra field in every intent broadcast by this class. It contains the BluetoothDevice
that the intent applies to.
Value: "android.bluetooth.device.extra.DEVICE"
EXTRA_IS_COORDINATED_SET_MEMBER
static val EXTRA_IS_COORDINATED_SET_MEMBER: String
Used as a boolean extra field in ACTION_FOUND
intents. It contains the information if device is discovered as member of a coordinated set or not. Pairing with device that belongs to a set would trigger pairing with the rest of set members. See Bluetooth CSIP specification for more details.
Value: "android.bluetooth.extra.IS_COORDINATED_SET_MEMBER"
EXTRA_NAME
static val EXTRA_NAME: String
Used as a String extra field in ACTION_NAME_CHANGED
and ACTION_FOUND
intents. It contains the friendly Bluetooth name.
Value: "android.bluetooth.device.extra.NAME"
EXTRA_PAIRING_KEY
static val EXTRA_PAIRING_KEY: String
Used as an int extra field in ACTION_PAIRING_REQUEST
intents as the value of passkey. The Bluetooth Passkey is a 6-digit numerical value represented as integer value in the range 0x00000000 – 0x000F423F (000000 to 999999).
Value: "android.bluetooth.device.extra.PAIRING_KEY"
EXTRA_PAIRING_VARIANT
static val EXTRA_PAIRING_VARIANT: String
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
,
Value: "android.bluetooth.device.extra.PAIRING_VARIANT"
EXTRA_PREVIOUS_BOND_STATE
static val EXTRA_PREVIOUS_BOND_STATE: String
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
.
Value: "android.bluetooth.device.extra.PREVIOUS_BOND_STATE"
EXTRA_RSSI
static val EXTRA_RSSI: String
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.
Value: "android.bluetooth.device.extra.RSSI"
EXTRA_TRANSPORT
static val EXTRA_TRANSPORT: String
Used as an int extra field in ACTION_ACL_CONNECTED
and ACTION_ACL_DISCONNECTED
intents to indicate which transport is connected. Possible values are: TRANSPORT_BREDR
and TRANSPORT_LE
.
Value: "android.bluetooth.device.extra.TRANSPORT"
EXTRA_UUID
static val EXTRA_UUID: String
Used as an extra field in ACTION_UUID
intents, Contains the s of the remote device which is a parcelable version of UUID
. A null
EXTRA_UUID indicates a timeout.
Value: "android.bluetooth.device.extra.UUID"
PAIRING_VARIANT_PASSKEY_CONFIRMATION
static val PAIRING_VARIANT_PASSKEY_CONFIRMATION: Int
The user will be prompted to confirm the passkey displayed on the screen or an app will confirm the passkey for the user.
Value: 2
PAIRING_VARIANT_PIN
static val PAIRING_VARIANT_PIN: Int
The user will be prompted to enter a pin or an app will enter a pin for user.
Value: 0
PHY_LE_1M
static val PHY_LE_1M: Int
Bluetooth LE 1M PHY. Used to refer to LE 1M Physical Channel for advertising, scanning or connection.
Value: 1
PHY_LE_1M_MASK
static val PHY_LE_1M_MASK: Int
Bluetooth LE 1M PHY mask. Used to specify LE 1M Physical Channel as one of many available options in a bitmask.
Value: 1
PHY_LE_2M
static val PHY_LE_2M: Int
Bluetooth LE 2M PHY. Used to refer to LE 2M Physical Channel for advertising, scanning or connection.
Value: 2
PHY_LE_2M_MASK
static val PHY_LE_2M_MASK: Int
Bluetooth LE 2M PHY mask. Used to specify LE 2M Physical Channel as one of many available options in a bitmask.
Value: 2
PHY_LE_CODED
static val PHY_LE_CODED: Int
Bluetooth LE Coded PHY. Used to refer to LE Coded Physical Channel for advertising, scanning or connection.
Value: 3
PHY_LE_CODED_MASK
static val PHY_LE_CODED_MASK: Int
Bluetooth LE Coded PHY mask. Used to specify LE Coded Physical Channel as one of many available options in a bitmask.
Value: 4
PHY_OPTION_NO_PREFERRED
static val PHY_OPTION_NO_PREFERRED: Int
No preferred coding when transmitting on the LE Coded PHY.
Value: 0
PHY_OPTION_S2
static val PHY_OPTION_S2: Int
Prefer the S=2 coding to be used when transmitting on the LE Coded PHY.
Value: 1
PHY_OPTION_S8
static val PHY_OPTION_S8: Int
Prefer the S=8 coding to be used when transmitting on the LE Coded PHY.
Value: 2
TRANSPORT_AUTO
static val TRANSPORT_AUTO: Int
No preference of physical transport for GATT connections to remote dual-mode devices
Value: 0
TRANSPORT_BREDR
static val TRANSPORT_BREDR: Int
Constant representing the BR/EDR transport.
Value: 1
TRANSPORT_LE
static val TRANSPORT_LE: Int
Constant representing the Bluetooth Low Energy (BLE) Transport.
Value: 2
Public methods
connectGatt
fun connectGatt(
context: Context!,
autoConnect: Boolean,
callback: BluetoothGattCallback!
): BluetoothGatt!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
callback |
BluetoothGattCallback!: GATT callback handler that will receive asynchronous callbacks. |
autoConnect |
Boolean: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if callback is null |
connectGatt
fun connectGatt(
context: Context!,
autoConnect: Boolean,
callback: BluetoothGattCallback!,
transport: Int
): BluetoothGatt!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
callback |
BluetoothGattCallback!: GATT callback handler that will receive asynchronous callbacks. |
autoConnect |
Boolean: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). |
transport |
Int: preferred transport for GATT connections to remote dual-mode devices android.bluetooth.BluetoothDevice#TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or android.bluetooth.BluetoothDevice#TRANSPORT_LE |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if callback is null |
connectGatt
fun connectGatt(
context: Context!,
autoConnect: Boolean,
callback: BluetoothGattCallback!,
transport: Int,
phy: Int
): BluetoothGatt!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
callback |
BluetoothGattCallback!: GATT callback handler that will receive asynchronous callbacks. |
autoConnect |
Boolean: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). |
transport |
Int: preferred transport for GATT connections to remote dual-mode devices android.bluetooth.BluetoothDevice#TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or android.bluetooth.BluetoothDevice#TRANSPORT_LE |
phy |
Int: preferred PHY for connections to remote LE device. Bitwise OR of any of android.bluetooth.BluetoothDevice#PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , and android.bluetooth.BluetoothDevice#PHY_LE_CODED_MASK . This option does not take effect if autoConnect is set to true. |
Exceptions | |
---|---|
java.lang.NullPointerException |
if callback is null |
connectGatt
fun connectGatt(
context: Context!,
autoConnect: Boolean,
callback: BluetoothGattCallback!,
transport: Int,
phy: Int,
handler: Handler!
): BluetoothGatt!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
callback |
BluetoothGattCallback!: GATT callback handler that will receive asynchronous callbacks. |
autoConnect |
Boolean: Whether to directly connect to the remote device (false) or to automatically connect as soon as the remote device becomes available (true). |
transport |
Int: preferred transport for GATT connections to remote dual-mode devices android.bluetooth.BluetoothDevice#TRANSPORT_AUTO or BluetoothDevice#TRANSPORT_BREDR or android.bluetooth.BluetoothDevice#TRANSPORT_LE |
phy |
Int: preferred PHY for connections to remote LE device. Bitwise OR of any of android.bluetooth.BluetoothDevice#PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , an dandroid.bluetooth.BluetoothDevice#PHY_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. |
Exceptions | |
---|---|
java.lang.NullPointerException |
if callback is null |
createBond
fun createBond(): Boolean
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
Boolean |
false on immediate error, true if bonding will begin |
createInsecureL2capChannel
fun createInsecureL2capChannel(psm: Int): BluetoothSocket
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 android.bluetooth.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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
psm |
Int: dynamic PSM value from remote device |
Return | |
---|---|
BluetoothSocket |
a CoC #BluetoothSocket ready for an outgoing connection This value cannot be null . |
Exceptions | |
---|---|
java.io.IOException |
on error, for example Bluetooth not available, or insufficient permissions |
createInsecureRfcommSocketToServiceRecord
fun createInsecureRfcommSocketToServiceRecord(uuid: UUID!): BluetoothSocket!
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
if an encrypted and authenticated communication channel is desired.
This is designed to be used with android.bluetooth.BluetoothAdapter#listenUsingInsecureRfcommWithServiceRecord
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
uuid |
UUID!: service record uuid to lookup RFCOMM channel |
Return | |
---|---|
BluetoothSocket! |
a RFCOMM BluetoothServerSocket ready for an outgoing connection |
Exceptions | |
---|---|
java.io.IOException |
on error, for example Bluetooth not available, or insufficient permissions |
createL2capChannel
fun createL2capChannel(psm: Int): BluetoothSocket
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
psm |
Int: dynamic PSM value from remote device |
Return | |
---|---|
BluetoothSocket |
a CoC #BluetoothSocket ready for an outgoing connection This value cannot be null . |
Exceptions | |
---|---|
java.io.IOException |
on error, for example Bluetooth not available, or insufficient permissions |
createRfcommSocketToServiceRecord
fun createRfcommSocketToServiceRecord(uuid: UUID!): BluetoothSocket!
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 android.bluetooth.BluetoothAdapter#listenUsingRfcommWithServiceRecord
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
. 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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Parameters | |
---|---|
uuid |
UUID!: service record uuid to lookup RFCOMM channel |
Return | |
---|---|
BluetoothSocket! |
a RFCOMM BluetoothServerSocket ready for an outgoing connection |
Exceptions | |
---|---|
java.io.IOException |
on error, for example Bluetooth not available, or insufficient permissions |
describeContents
fun describeContents(): Int
Return | |
---|---|
Int |
a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR |
equals
fun equals(other: Any?): Boolean
Indicates whether some other object is "equal to" this one.
The equals
method implements an equivalence relation on non-null object references:
- It is reflexive: for any non-null reference value
x
,x.equals(x)
should returntrue
. - It is symmetric: for any non-null reference values
x
andy
,x.equals(y)
should returntrue
if and only ify.equals(x)
returnstrue
. - It is transitive: for any non-null reference values
x
,y
, andz
, ifx.equals(y)
returnstrue
andy.equals(z)
returnstrue
, thenx.equals(z)
should returntrue
. - It is consistent: for any non-null reference values
x
andy
, multiple invocations ofx.equals(y)
consistently returntrue
or consistently returnfalse
, provided no information used inequals
comparisons on the objects is modified. - For any non-null reference value
x
,x.equals(null)
should returnfalse
.
An equivalence relation partitions the elements it operates on into equivalence classes; all the members of an equivalence class are equal to each other. Members of an equivalence class are substitutable for each other, at least for some purposes.
Parameters | |
---|---|
obj |
the reference object with which to compare. |
o |
This value may be null . |
Return | |
---|---|
Boolean |
true if this object is the same as the obj argument; false otherwise. |
fetchUuidsWithSdp
fun fetchUuidsWithSdp(): Boolean
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
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. |
getAddress
fun getAddress(): String!
Returns the hardware address of this BluetoothDevice.
For example, "00:11:22:AA:BB:CC".
Return | |
---|---|
String! |
Bluetooth hardware address as string |
getAddressType
fun getAddressType(): Int
Returns the address type of this BluetoothDevice, one of ADDRESS_TYPE_PUBLIC, , ADDRESS_TYPE_ANONYMOUS, or ADDRESS_TYPE_UNKNOWN.
getAlias
fun getAlias(): String?
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
String? |
the Bluetooth alias, the friendly device name if no alias, or null if there was a problem |
getBluetoothClass
fun getBluetoothClass(): BluetoothClass!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
BluetoothClass! |
Bluetooth class object, or null on error |
getBondState
fun getBondState(): Int
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
Int |
the bond state |
getName
fun getName(): String!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
String! |
the Bluetooth name, or null if there was a problem. |
getType
fun getType(): Int
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
Int |
the device type DEVICE_TYPE_CLASSIC , DEVICE_TYPE_LE DEVICE_TYPE_DUAL . DEVICE_TYPE_UNKNOWN if it's not available |
getUuids
fun getUuids(): Array<ParcelUuid!>!
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
Array<ParcelUuid!>! |
the supported features (UUIDs) of the remote device, or null on error |
setAlias
fun setAlias(alias: String?): Int
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 android.companion.CompanionDeviceManager#associate(AssociationRequest, * android.companion.CompanionDeviceManager.Callback, Handler)) and have the android.Manifest.permission#BLUETOOTH_CONNECT
permission. Alternatively, if the caller has the android.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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.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. |
Exceptions | |
---|---|
java.lang.IllegalArgumentException |
if the alias is the empty string |
setPairingConfirmation
fun setPairingConfirmation(confirm: Boolean): Boolean
Confirm passkey for PAIRING_VARIANT_PASSKEY_CONFIRMATION
pairing.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
and android.Manifest.permission#BLUETOOTH_PRIVILEGED
Return | |
---|---|
Boolean |
true confirmation has been sent out false for error |
setPin
fun setPin(pin: ByteArray!): Boolean
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 android.app.Activity#requestPermissions(String[], int)
.
Requires android.Manifest.permission#BLUETOOTH_CONNECT
Return | |
---|---|
Boolean |
true pin has been set false for error |
toString
fun toString(): String
Returns a string representation of this BluetoothDevice.
For apps targeting android.os.Build.VERSION_CODES#UPSIDE_DOWN_CAKE
(API level 34) or higher, this returns the MAC address of the device redacted by replacing the hexadecimal digits of leftmost 4 bytes (in big endian order) with "XX", e.g., "XX:XX:XX:XX:12:34". For apps targeting earlier versions, the MAC address is returned without redaction.
Warning: The return value of toString()
may change in the future. It is intended to be used in logging statements. Thus apps should never rely on the return value of toString()
in their logic. Always use other appropriate APIs instead (e.g., use getAddress()
to get the MAC address).
Return | |
---|---|
String |
string representation of this BluetoothDevice |
writeToParcel
fun writeToParcel(
out: Parcel,
flags: Int
): Unit
Parameters | |
---|---|
dest |
The Parcel in which the object should be written. This value cannot be null . |
flags |
Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE . Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |