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 |
GATT connection timed out, likely due to the remote device being out of range or not advertising as connectable. |
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 |
abortReliableWrite(mDevice: BluetoothDevice!)
|
Boolean |
Initiates a reliable write transaction for a given remote device. |
Unit |
close() Close this Bluetooth GATT client. |
Boolean |
connect() 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 |
getConnectionState(device: BluetoothDevice!) |
BluetoothDevice! |
Return the remote bluetooth device this GATT client targets to |
MutableList<BluetoothDevice!>! |
getDevicesMatchingConnectionStates(states: IntArray!) |
BluetoothGattService! |
getService(uuid: UUID!) Returns a |
MutableList<BluetoothGattService!>! |
Returns a list of GATT services offered by the remote device. |
Boolean |
readCharacteristic(characteristic: BluetoothGattCharacteristic!) Reads the requested characteristic from the associated remote device. |
Boolean |
readDescriptor(descriptor: BluetoothGattDescriptor!) Reads the value for a given descriptor from the associated remote device. |
Unit |
readPhy() 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 |
requestMtu(mtu: Int) Request an MTU size used for a given connection. |
Boolean |
setCharacteristicNotification(characteristic: BluetoothGattCharacteristic!, enable: 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 |
writeCharacteristic(characteristic: BluetoothGattCharacteristic!) 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 |
writeDescriptor(descriptor: BluetoothGattDescriptor!) Write the value of a given descriptor to the associated remote device. |
Int |
writeDescriptor(descriptor: BluetoothGattDescriptor, value: ByteArray) Write the value of a given descriptor to the associated remote device. |
Constants
CONNECTION_PRIORITY_BALANCED
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
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
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
static val CONNECTION_PRIORITY_LOW_POWER: Int
Connection parameter update - Request low power, reduced data rate connection parameters.
Value: 2
GATT_CONNECTION_CONGESTED
static val GATT_CONNECTION_CONGESTED: Int
A remote device connection is congested.
Value: 143
GATT_CONNECTION_TIMEOUT
static val GATT_CONNECTION_TIMEOUT: Int
GATT connection timed out, likely due to the remote device being out of range or not advertising as connectable.
Value: 147
GATT_FAILURE
static val GATT_FAILURE: Int
A GATT operation failed, errors other than the above
Value: 257
GATT_INSUFFICIENT_AUTHENTICATION
static val GATT_INSUFFICIENT_AUTHENTICATION: Int
Insufficient authentication for a given operation
Value: 5
GATT_INSUFFICIENT_AUTHORIZATION
static val GATT_INSUFFICIENT_AUTHORIZATION: Int
Insufficient authorization for a given operation
Value: 8
GATT_INSUFFICIENT_ENCRYPTION
static val GATT_INSUFFICIENT_ENCRYPTION: Int
Insufficient encryption for a given operation
Value: 15
GATT_INVALID_ATTRIBUTE_LENGTH
static val GATT_INVALID_ATTRIBUTE_LENGTH: Int
A write operation exceeds the maximum length of the attribute
Value: 13
GATT_INVALID_OFFSET
static val GATT_INVALID_OFFSET: Int
A read or write operation was requested with an invalid offset
Value: 7
GATT_READ_NOT_PERMITTED
static val GATT_READ_NOT_PERMITTED: Int
GATT read operation is not permitted
Value: 2
GATT_REQUEST_NOT_SUPPORTED
static val GATT_REQUEST_NOT_SUPPORTED: Int
The given request is not supported
Value: 6
GATT_SUCCESS
static val GATT_SUCCESS: Int
A GATT operation completed successfully
Value: 0
GATT_WRITE_NOT_PERMITTED
static val GATT_WRITE_NOT_PERMITTED: Int
GATT write operation is not permitted
Value: 3
Public methods
abortReliableWrite
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
funabortReliableWrite(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
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
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
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
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
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
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
fungetConnectedDevices(): 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
fungetConnectionState(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
fun getDevice(): BluetoothDevice!
Return the remote bluetooth device this GATT client targets to
Return | |
---|---|
BluetoothDevice! |
remote bluetooth device |
getDevicesMatchingConnectionStates
fungetDevicesMatchingConnectionStates(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
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
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
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
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
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
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
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
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
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
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
funwriteCharacteristic(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
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
funwriteDescriptor(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
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 |