Added in API level 18

BluetoothGatt

class BluetoothGatt : BluetoothProfile
kotlin.Any
   ↳ android.bluetooth.BluetoothGatt

Public API for the Bluetooth GATT Profile.

This class provides Bluetooth GATT functionality to enable communication with Bluetooth Smart or Smart Ready devices.

To connect to a remote peripheral device, create a BluetoothGattCallback and call android.bluetooth.BluetoothDevice#connectGatt to get a instance of this class. GATT capable devices can be discovered using the Bluetooth device discovery or BLE scan process.

Summary

Constants
static Int

Connection parameter update - Use the connection parameters recommended by the Bluetooth SIG.

static Int

Connection parameter update - Request the priority preferred for Digital Car Key for a lower latency connection.

static Int

Connection parameter update - Request a high priority, low latency connection.

static Int

Connection parameter update - Request low power, reduced data rate connection parameters.

static Int

A remote device connection is congested.

static Int

A GATT operation failed, errors other than the above

static Int

Insufficient authentication for a given operation

static Int

Insufficient authorization for a given operation

static Int

Insufficient encryption for a given operation

static Int

A write operation exceeds the maximum length of the attribute

static Int

A read or write operation was requested with an invalid offset

static Int

GATT read operation is not permitted

static Int

The given request is not supported

static Int

A GATT operation completed successfully

static Int

GATT write operation is not permitted

Inherited constants
Public methods
Unit

Cancels a reliable write transaction for a given device.

Unit


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).

Boolean

Initiates a reliable write transaction for a given remote device.

Unit

Close this Bluetooth GATT client.

Boolean

Connect back to remote device.

Unit

Disconnects an established connection, or cancels a connection attempt currently in progress.

Boolean

Discovers services offered by a remote device as well as their characteristics and descriptors.

Boolean

Executes a reliable write transaction for a given remote device.

MutableList<BluetoothDevice!>!

Int

BluetoothDevice!

Return the remote bluetooth device this GATT client targets to

MutableList<BluetoothDevice!>!

BluetoothGattService!
getService(uuid: UUID!)

Returns a BluetoothGattService, if the requested UUID is supported by the remote device.

MutableList<BluetoothGattService!>!

Returns a list of GATT services offered by the remote device.

Boolean

Reads the requested characteristic from the associated remote device.

Boolean

Reads the value for a given descriptor from the associated remote device.

Unit

Read the current transmitter PHY and receiver PHY of the connection.

Boolean

Read the RSSI for a connected remote device.

Boolean
requestConnectionPriority(connectionPriority: Int)

Request a connection parameter update.

Boolean

Request an MTU size used for a given connection.

Boolean

Enable or disable notifications/indications for a given characteristic.

Unit
setPreferredPhy(txPhy: Int, rxPhy: Int, phyOptions: Int)

Set the preferred connection PHY for this app.

Boolean

Writes a given characteristic and its values to the associated remote device.

Int
writeCharacteristic(characteristic: BluetoothGattCharacteristic, value: ByteArray, writeType: Int)

Writes a given characteristic and its values to the associated remote device.

Boolean

Write the value of a given descriptor to the associated remote device.

Int

Write the value of a given descriptor to the associated remote device.

Constants

CONNECTION_PRIORITY_BALANCED

Added in API level 21
static val CONNECTION_PRIORITY_BALANCED: Int

Connection parameter update - Use the connection parameters recommended by the Bluetooth SIG. This is the default value if no connection parameter update is requested.

Value: 0

CONNECTION_PRIORITY_DCK

Added in API level 34
static val CONNECTION_PRIORITY_DCK: Int

Connection parameter update - Request the priority preferred for Digital Car Key for a lower latency connection. This connection parameter will consume more power than android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_BALANCED, so it is recommended that apps do not use this unless it specifically fits their use case.

Value: 3

CONNECTION_PRIORITY_HIGH

Added in API level 21
static val CONNECTION_PRIORITY_HIGH: Int

Connection parameter update - Request a high priority, low latency connection. An application should only request high priority connection parameters to transfer large amounts of data over LE quickly. Once the transfer is complete, the application should request android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_BALANCED connection parameters to reduce energy use.

Value: 1

CONNECTION_PRIORITY_LOW_POWER

Added in API level 21
static val CONNECTION_PRIORITY_LOW_POWER: Int

Connection parameter update - Request low power, reduced data rate connection parameters.

Value: 2

GATT_CONNECTION_CONGESTED

Added in API level 21
static val GATT_CONNECTION_CONGESTED: Int

A remote device connection is congested.

Value: 143

GATT_FAILURE

Added in API level 18
static val GATT_FAILURE: Int

A GATT operation failed, errors other than the above

Value: 257

GATT_INSUFFICIENT_AUTHENTICATION

Added in API level 18
static val GATT_INSUFFICIENT_AUTHENTICATION: Int

Insufficient authentication for a given operation

Value: 5

GATT_INSUFFICIENT_AUTHORIZATION

Added in API level 33
static val GATT_INSUFFICIENT_AUTHORIZATION: Int

Insufficient authorization for a given operation

Value: 8

GATT_INSUFFICIENT_ENCRYPTION

Added in API level 18
static val GATT_INSUFFICIENT_ENCRYPTION: Int

Insufficient encryption for a given operation

Value: 15

GATT_INVALID_ATTRIBUTE_LENGTH

Added in API level 18
static val GATT_INVALID_ATTRIBUTE_LENGTH: Int

A write operation exceeds the maximum length of the attribute

Value: 13

GATT_INVALID_OFFSET

Added in API level 18
static val GATT_INVALID_OFFSET: Int

A read or write operation was requested with an invalid offset

Value: 7

GATT_READ_NOT_PERMITTED

Added in API level 18
static val GATT_READ_NOT_PERMITTED: Int

GATT read operation is not permitted

Value: 2

GATT_REQUEST_NOT_SUPPORTED

Added in API level 18
static val GATT_REQUEST_NOT_SUPPORTED: Int

The given request is not supported

Value: 6

GATT_SUCCESS

Added in API level 18
static val GATT_SUCCESS: Int

A GATT operation completed successfully

Value: 0

GATT_WRITE_NOT_PERMITTED

Added in API level 18
static val GATT_WRITE_NOT_PERMITTED: Int

GATT write operation is not permitted

Value: 3

Public methods

abortReliableWrite

Added in API level 19
fun abortReliableWrite(): Unit

Cancels a reliable write transaction for a given device.

Calling this function will discard all queued characteristic write operations for a given 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

abortReliableWrite

Added in API level 18
Deprecated in API level 19
fun abortReliableWrite(mDevice: BluetoothDevice!): Unit

Deprecated: Use abortReliableWrite()


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

beginReliableWrite

Added in API level 18
fun beginReliableWrite(): Boolean

Initiates a reliable write transaction for a given remote device.

Once a reliable write transaction has been initiated, all calls to #writeCharacteristic are sent to the remote device for verification and queued up for atomic execution. The application will receive a BluetoothGattCallback#onCharacteristicWrite callback in response to every writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic,byte[],int) call and is responsible for verifying if the value has been transmitted accurately.

After all characteristics have been queued up and verified, executeReliableWrite will execute all writes. If a characteristic was not written correctly, calling #abortReliableWrite will cancel the current transaction without committing any values on 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
Boolean true, if the reliable write transaction has been initiated

close

Added in API level 18
fun close(): Unit

Close this Bluetooth GATT client.

Application should call this method as early as possible after it is done with this GATT client.
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

connect

Added in API level 18
fun connect(): Boolean

Connect back to remote device.

This method is used to re-connect to a remote device after the connection has been dropped. If the device is not in range, the re-connection will be triggered once the device is back in range.
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, if the connection attempt was initiated successfully

disconnect

Added in API level 18
fun disconnect(): Unit

Disconnects an established connection, or cancels a connection attempt currently in progress.
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

discoverServices

Added in API level 18
fun discoverServices(): Boolean

Discovers services offered by a remote device as well as their characteristics and descriptors.

This is an asynchronous operation. Once service discovery is completed, the android.bluetooth.BluetoothGattCallback#onServicesDiscovered callback is triggered. If the discovery was successful, the remote services can be retrieved using the getServices function.
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 true, if the remote service discovery has been started

executeReliableWrite

Added in API level 18
fun executeReliableWrite(): Boolean

Executes a reliable write transaction for a given remote device.

This function will commit all queued up characteristic write operations for a given remote device.

A BluetoothGattCallback#onReliableWriteCompleted callback is invoked to indicate whether the transaction has been executed correctly.
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 true, if the request to execute the transaction has been sent

getConnectedDevices

Added in API level 18
fun getConnectedDevices(): MutableList<BluetoothDevice!>!

Deprecated: Not supported - please use BluetoothManager#getConnectedDevices(int) with BluetoothProfile#GATT as argument

Return
MutableList<BluetoothDevice!>! List of devices. The list will be empty on error.
Exceptions
java.lang.UnsupportedOperationException on every call

getConnectionState

Added in API level 18
fun getConnectionState(device: BluetoothDevice!): Int

Deprecated: Not supported - please use BluetoothManager#getConnectedDevices(int) with BluetoothProfile#GATT as argument

Parameters
device BluetoothDevice!: Remote bluetooth device.
Return
Int State of the profile connection. One of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING Value is android.bluetooth.BluetoothProfile#STATE_DISCONNECTED, android.bluetooth.BluetoothProfile#STATE_CONNECTING, android.bluetooth.BluetoothProfile#STATE_CONNECTED, or android.bluetooth.BluetoothProfile#STATE_DISCONNECTING
Exceptions
java.lang.UnsupportedOperationException on every call

getDevice

Added in API level 18
fun getDevice(): BluetoothDevice!

Return the remote bluetooth device this GATT client targets to

Return
BluetoothDevice! remote bluetooth device

getDevicesMatchingConnectionStates

Added in API level 18
fun getDevicesMatchingConnectionStates(states: IntArray!): MutableList<BluetoothDevice!>!

Deprecated: Not supported - please use android.bluetooth.BluetoothManager#getDevicesMatchingConnectionStates(int,int[]) with android.bluetooth.BluetoothProfile#GATT as first argument

Parameters
states IntArray!: Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING,
Return
MutableList<BluetoothDevice!>! List of devices. The list will be empty on error.
Exceptions
java.lang.UnsupportedOperationException on every call

getService

Added in API level 18
fun getService(uuid: UUID!): BluetoothGattService!

Returns a BluetoothGattService, if the requested UUID is supported by the remote device.

This function requires that service discovery has been completed for the given device.

If multiple instances of the same service (as identified by UUID) exist, the first instance of the service is returned.
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.

Parameters
uuid UUID!: UUID of the requested service
Return
BluetoothGattService! BluetoothGattService if supported, or null if the requested service is not offered by the remote device.

getServices

Added in API level 18
fun getServices(): MutableList<BluetoothGattService!>!

Returns a list of GATT services offered by the remote device.

This function requires that service discovery has been completed for the given 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.

Return
MutableList<BluetoothGattService!>! List of services on the remote device. Returns an empty list if service discovery has not yet been performed.

readCharacteristic

Added in API level 18
fun readCharacteristic(characteristic: BluetoothGattCharacteristic!): Boolean

Reads the requested characteristic from the associated remote device.

This is an asynchronous operation. The result of the read operation is reported by the BluetoothGattCallback#onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, callback.
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
characteristic BluetoothGattCharacteristic!: Characteristic to read from the remote device
Return
Boolean true, if the read operation was initiated successfully

readDescriptor

Added in API level 18
fun readDescriptor(descriptor: BluetoothGattDescriptor!): Boolean

Reads the value for a given descriptor from the associated remote device.

Once the read operation has been completed, the android.bluetooth.BluetoothGattCallback#onDescriptorRead callback is triggered, signaling the result of the operation.
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
descriptor BluetoothGattDescriptor!: Descriptor value to read from the remote device
Return
Boolean true, if the read operation was initiated successfully

readPhy

Added in API level 26
fun readPhy(): Unit

Read the current transmitter PHY and receiver PHY of the connection. The values are returned in BluetoothGattCallback#onPhyRead
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

readRemoteRssi

Added in API level 18
fun readRemoteRssi(): Boolean

Read the RSSI for a connected remote device.

The BluetoothGattCallback#onReadRemoteRssi callback will be invoked when the RSSI value has been read.
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 true, if the RSSI value has been requested successfully

requestConnectionPriority

Added in API level 21
fun requestConnectionPriority(connectionPriority: Int): Boolean

Request a connection parameter update.

This function will send a connection parameter update request to the remote device.
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
connectionPriority Int: Request a specific connection priority. Must be one of android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_BALANCED, android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_HIGH android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_LOW_POWER, or android.bluetooth.BluetoothGatt#CONNECTION_PRIORITY_DCK.
Exceptions
java.lang.IllegalArgumentException If the parameters are outside of their specified range.

requestMtu

Added in API level 21
fun requestMtu(mtu: Int): Boolean

Request an MTU size used for a given connection. Please note that starting from Android 14, the Android Bluetooth stack requests the BLE ATT MTU to 517 bytes when the first GATT client requests an MTU, and disregards all subsequent MTU requests. Check out MTU is set to 517 for the first GATT client requesting an MTU for more information.

When performing a write request operation (write without response), the data sent is truncated to the MTU size. This function may be used to request a larger MTU size to be able to send more data at once.

A BluetoothGattCallback#onMtuChanged callback will indicate whether this operation was successful.
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 true, if the new MTU value has been requested successfully

setCharacteristicNotification

Added in API level 18
fun setCharacteristicNotification(
    characteristic: BluetoothGattCharacteristic!,
    enable: Boolean
): Boolean

Enable or disable notifications/indications for a given characteristic.

Once notifications are enabled for a characteristic, a android.bluetooth.BluetoothGattCallback#onCharacteristicChanged(android.bluetooth.BluetoothGatt,android.bluetooth.BluetoothGattCharacteristic,byte[]) callback will be triggered if the remote device indicates that the given characteristic has changed.
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
characteristic BluetoothGattCharacteristic!: The characteristic for which to enable notifications
enable Boolean: Set to true to enable notifications/indications
Return
Boolean true, if the requested notification status was set successfully

setPreferredPhy

Added in API level 26
fun setPreferredPhy(
    txPhy: Int,
    rxPhy: Int,
    phyOptions: Int
): Unit

Set the preferred connection PHY for this app. Please note that this is just a recommendation, whether the PHY change will happen depends on other applications preferences, local and remote controller capabilities. Controller can override these settings.

BluetoothGattCallback#onPhyUpdate will be triggered as a result of this call, even if no PHY change happens. It is also triggered when remote device updates the PHY.
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
txPhy Int: preferred transmitter PHY. 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.
rxPhy Int: preferred receiver PHY. 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.
phyOptions Int: preferred coding to use when transmitting on the LE Coded PHY. Can be one of BluetoothDevice#PHY_OPTION_NO_PREFERRED, BluetoothDevice#PHY_OPTION_S2 or BluetoothDevice#PHY_OPTION_S8

writeCharacteristic

Added in API level 18
Deprecated in API level 33
fun writeCharacteristic(characteristic: BluetoothGattCharacteristic!): Boolean

Deprecated: Use BluetoothGatt#writeCharacteristic(BluetoothGattCharacteristic, byte[], as this is not memory safe because it relies on a BluetoothGattCharacteristic object whose underlying fields are subject to change outside this method.

Writes a given characteristic and its values to the associated remote device.

Once the write operation has been completed, the android.bluetooth.BluetoothGattCallback#onCharacteristicWrite callback is invoked, reporting the result of the operation.
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
characteristic BluetoothGattCharacteristic!: Characteristic to write on the remote device
Return
Boolean true, if the write operation was initiated successfully
Exceptions
java.lang.IllegalArgumentException if characteristic or its value are null

writeCharacteristic

Added in API level 33
fun writeCharacteristic(
    characteristic: BluetoothGattCharacteristic,
    value: ByteArray,
    writeType: Int
): Int

Writes a given characteristic and its values to the associated remote device.

Once the write operation has been completed, the android.bluetooth.BluetoothGattCallback#onCharacteristicWrite callback is invoked, reporting the result of the operation.
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
characteristic BluetoothGattCharacteristic: Characteristic to write on the remote device This value cannot be null.
value ByteArray: This value cannot be null.
writeType Int: Value is android.bluetooth.BluetoothGattCharacteristic#WRITE_TYPE_DEFAULT, android.bluetooth.BluetoothGattCharacteristic#WRITE_TYPE_NO_RESPONSE, or android.bluetooth.BluetoothGattCharacteristic#WRITE_TYPE_SIGNED
Return
Int whether the characteristic was successfully written to Value is android.bluetooth.BluetoothStatusCodes#SUCCESS, android.bluetooth.BluetoothStatusCodes#ERROR_MISSING_BLUETOOTH_CONNECT_PERMISSION, android.bluetooth.BluetoothStatusCodes.ERROR_DEVICE_NOT_CONNECTED, android.bluetooth.BluetoothStatusCodes#ERROR_PROFILE_SERVICE_NOT_BOUND, android.bluetooth.BluetoothStatusCodes#ERROR_GATT_WRITE_NOT_ALLOWED, android.bluetooth.BluetoothStatusCodes#ERROR_GATT_WRITE_REQUEST_BUSY, or android.bluetooth.BluetoothStatusCodes#ERROR_UNKNOWN
Exceptions
java.lang.IllegalArgumentException if characteristic or value are null

writeDescriptor

Added in API level 18
Deprecated in API level 33
fun writeDescriptor(descriptor: BluetoothGattDescriptor!): Boolean

Deprecated: Use BluetoothGatt#writeDescriptor(BluetoothGattDescriptor, byte[]) as this is not memory safe because it relies on a BluetoothGattDescriptor object whose underlying fields are subject to change outside this method.

Write the value of a given descriptor to the associated remote device.

A BluetoothGattCallback#onDescriptorWrite callback is triggered to report the result of the write operation.
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
descriptor BluetoothGattDescriptor!: Descriptor to write to the associated remote device
Return
Boolean true, if the write operation was initiated successfully
Exceptions
java.lang.IllegalArgumentException if descriptor or its value are null

writeDescriptor

Added in API level 33
fun writeDescriptor(
    descriptor: BluetoothGattDescriptor,
    value: ByteArray
): Int

Write the value of a given descriptor to the associated remote device.

A BluetoothGattCallback#onDescriptorWrite callback is triggered to report the result of the write operation.
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
descriptor BluetoothGattDescriptor: Descriptor to write to the associated remote device This value cannot be null.
value ByteArray: This value cannot be null.
Return
Int true, if the write operation was initiated successfully Value is android.bluetooth.BluetoothStatusCodes#SUCCESS, android.bluetooth.BluetoothStatusCodes#ERROR_MISSING_BLUETOOTH_CONNECT_PERMISSION, android.bluetooth.BluetoothStatusCodes.ERROR_DEVICE_NOT_CONNECTED, android.bluetooth.BluetoothStatusCodes#ERROR_PROFILE_SERVICE_NOT_BOUND, android.bluetooth.BluetoothStatusCodes#ERROR_GATT_WRITE_NOT_ALLOWED, android.bluetooth.BluetoothStatusCodes#ERROR_GATT_WRITE_REQUEST_BUSY, or android.bluetooth.BluetoothStatusCodes#ERROR_UNKNOWN
Exceptions
java.lang.IllegalArgumentException if descriptor or value are null