# Print output for @column tags ?>
public
final
class
BluetoothGatt
extends Object
implements
BluetoothProfile
java.lang.Object | |
↳ | 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 BluetoothDevice#connectGatt
to get a instance of this class.
GATT capable devices can be discovered using the Bluetooth device discovery or BLE
scan process.
Constants | |
---|---|
int |
CONNECTION_PRIORITY_BALANCED
Connection parameter update - Use the connection parameters recommended by the Bluetooth SIG. |
int |
CONNECTION_PRIORITY_HIGH
Connection parameter update - Request a high priority, low latency connection. |
int |
CONNECTION_PRIORITY_LOW_POWER
Connection parameter update - Request low power, reduced data rate connection parameters. |
int |
GATT_CONNECTION_CONGESTED
A remote device connection is congested. |
int |
GATT_FAILURE
A GATT operation failed, errors other than the above |
int |
GATT_INSUFFICIENT_AUTHENTICATION
Insufficient authentication for a given operation |
int |
GATT_INSUFFICIENT_ENCRYPTION
Insufficient encryption for a given operation |
int |
GATT_INVALID_ATTRIBUTE_LENGTH
A write operation exceeds the maximum length of the attribute |
int |
GATT_INVALID_OFFSET
A read or write operation was requested with an invalid offset |
int |
GATT_READ_NOT_PERMITTED
GATT read operation is not permitted |
int |
GATT_REQUEST_NOT_SUPPORTED
The given request is not supported |
int |
GATT_SUCCESS
A GATT operation completed successfully |
int |
GATT_WRITE_NOT_PERMITTED
GATT write operation is not permitted |
Inherited constants |
---|
Public methods | |
---|---|
void
|
abortReliableWrite(BluetoothDevice mDevice)
This method is deprecated.
Use |
void
|
abortReliableWrite()
Cancels a reliable write transaction for a given device. |
boolean
|
beginReliableWrite()
Initiates a reliable write transaction for a given remote device. |
void
|
close()
Close this Bluetooth GATT client. |
boolean
|
connect()
Connect back to remote device. |
void
|
disconnect()
Disconnects an established connection, or cancels a connection attempt currently in progress. |
boolean
|
discoverServices()
Discovers services offered by a remote device as well as their characteristics and descriptors. |
boolean
|
executeReliableWrite()
Executes a reliable write transaction for a given remote device. |
List<BluetoothDevice>
|
getConnectedDevices()
Not supported - please use |
int
|
getConnectionState(BluetoothDevice device)
Not supported - please use |
BluetoothDevice
|
getDevice()
Return the remote bluetooth device this GATT client targets to |
List<BluetoothDevice>
|
getDevicesMatchingConnectionStates(int[] states)
Not supported - please use
|
BluetoothGattService
|
getService(UUID uuid)
Returns a |
List<BluetoothGattService>
|
getServices()
Returns a list of GATT services offered by the remote device. |
boolean
|
readCharacteristic(BluetoothGattCharacteristic characteristic)
Reads the requested characteristic from the associated remote device. |
boolean
|
readDescriptor(BluetoothGattDescriptor descriptor)
Reads the value for a given descriptor from the associated remote device. |
void
|
readPhy()
Read the current transmitter PHY and receiver PHY of the connection. |
boolean
|
readRemoteRssi()
Read the RSSI for a connected remote device. |
boolean
|
requestConnectionPriority(int connectionPriority)
Request a connection parameter update. |
boolean
|
requestMtu(int mtu)
Request an MTU size used for a given connection. |
boolean
|
setCharacteristicNotification(BluetoothGattCharacteristic characteristic, boolean enable)
Enable or disable notifications/indications for a given characteristic. |
void
|
setPreferredPhy(int txPhy, int rxPhy, int phyOptions)
Set the preferred connection PHY for this app. |
boolean
|
writeCharacteristic(BluetoothGattCharacteristic characteristic)
Writes a given characteristic and its values to the associated remote device. |
boolean
|
writeDescriptor(BluetoothGattDescriptor descriptor)
Write the value of a given descriptor to the associated remote device. |
Inherited methods | |
---|---|
public static final int CONNECTION_PRIORITY_BALANCED
Connection parameter update - Use the connection parameters recommended by the Bluetooth SIG. This is the default value if no connection parameter update is requested.
Constant Value: 0 (0x00000000)
public static final int CONNECTION_PRIORITY_HIGH
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 BluetoothGatt#CONNECTION_PRIORITY_BALANCED
connection parameters to reduce
energy use.
Constant Value: 1 (0x00000001)
public static final int CONNECTION_PRIORITY_LOW_POWER
Connection parameter update - Request low power, reduced data rate connection parameters.
Constant Value: 2 (0x00000002)
public static final int GATT_CONNECTION_CONGESTED
A remote device connection is congested.
Constant Value: 143 (0x0000008f)
public static final int GATT_FAILURE
A GATT operation failed, errors other than the above
Constant Value: 257 (0x00000101)
public static final int GATT_INSUFFICIENT_AUTHENTICATION
Insufficient authentication for a given operation
Constant Value: 5 (0x00000005)
public static final int GATT_INSUFFICIENT_ENCRYPTION
Insufficient encryption for a given operation
Constant Value: 15 (0x0000000f)
public static final int GATT_INVALID_ATTRIBUTE_LENGTH
A write operation exceeds the maximum length of the attribute
Constant Value: 13 (0x0000000d)
public static final int GATT_INVALID_OFFSET
A read or write operation was requested with an invalid offset
Constant Value: 7 (0x00000007)
public static final int GATT_READ_NOT_PERMITTED
GATT read operation is not permitted
Constant Value: 2 (0x00000002)
public static final int GATT_REQUEST_NOT_SUPPORTED
The given request is not supported
Constant Value: 6 (0x00000006)
public static final int GATT_SUCCESS
A GATT operation completed successfully
Constant Value: 0 (0x00000000)
public static final int GATT_WRITE_NOT_PERMITTED
GATT write operation is not permitted
Constant Value: 3 (0x00000003)
public void abortReliableWrite (BluetoothDevice mDevice)
This method is 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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
mDevice |
BluetoothDevice |
public void abortReliableWrite ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
public boolean beginReliableWrite ()
Initiates a reliable write transaction for a given remote device.
Once a reliable write transaction has been initiated, all calls
to writeCharacteristic(BluetoothGattCharacteristic)
are sent to the remote device for
verification and queued up for atomic execution. The application will
receive an BluetoothGattCallback#onCharacteristicWrite
callback
in response to every writeCharacteristic(BluetoothGattCharacteristic)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
true, if the reliable write transaction has been initiated |
public void close ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
public boolean connect ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
true, if the connection attempt was initiated successfully |
public void disconnect ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
public boolean discoverServices ()
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 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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
true, if the remote service discovery has been started |
public boolean executeReliableWrite ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
true, if the request to execute the transaction has been sent |
public List<BluetoothDevice> getConnectedDevices ()
Not supported - please use BluetoothManager#getConnectedDevices(int)
with BluetoothProfile#GATT
as argument
Returns | |
---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
Throws | |
---|---|
|
java.lang.UnsupportedOperationException |
public int getConnectionState (BluetoothDevice device)
Not supported - please use BluetoothManager#getConnectedDevices(int)
with BluetoothProfile#GATT
as argument
Parameters | |
---|---|
device |
BluetoothDevice : Remote bluetooth device. |
Returns | |
---|---|
int |
State of the profile connection. One of STATE_CONNECTED , STATE_CONNECTING , STATE_DISCONNECTED , STATE_DISCONNECTING
Value is STATE_DISCONNECTED , STATE_CONNECTING , STATE_CONNECTED , or STATE_DISCONNECTING |
Throws | |
---|---|
|
java.lang.UnsupportedOperationException |
public BluetoothDevice getDevice ()
Return the remote bluetooth device this GATT client targets to
Returns | |
---|---|
BluetoothDevice |
remote bluetooth device |
public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)
Not supported - please use
BluetoothManager#getDevicesMatchingConnectionStates(int, int[])
with BluetoothProfile#GATT
as first argument
Parameters | |
---|---|
states |
int : Array of states. States can be one of BluetoothProfile.STATE_CONNECTED , BluetoothProfile.STATE_CONNECTING , BluetoothProfile.STATE_DISCONNECTED , BluetoothProfile.STATE_DISCONNECTING , |
Returns | |
---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
Throws | |
---|---|
|
java.lang.UnsupportedOperationException |
public BluetoothGattService getService (UUID uuid)
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 |
Returns | |
---|---|
BluetoothGattService |
BluetoothGattService if supported, or null if the requested service is not offered by the remote device. |
public List<BluetoothGattService> getServices ()
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.
Returns | |
---|---|
List<BluetoothGattService> |
List of services on the remote device. Returns an empty list if service discovery has not yet been performed. |
public boolean readCharacteristic (BluetoothGattCharacteristic characteristic)
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
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
characteristic |
BluetoothGattCharacteristic : Characteristic to read from the remote device |
Returns | |
---|---|
boolean |
true, if the read operation was initiated successfully |
public boolean readDescriptor (BluetoothGattDescriptor descriptor)
Reads the value for a given descriptor from the associated remote device.
Once the read operation has been completed, the
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
descriptor |
BluetoothGattDescriptor : Descriptor value to read from the remote device |
Returns | |
---|---|
boolean |
true, if the read operation was initiated successfully |
public void readPhy ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
public boolean readRemoteRssi ()
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Returns | |
---|---|
boolean |
true, if the RSSI value has been requested successfully |
public boolean requestConnectionPriority (int connectionPriority)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
connectionPriority |
int : Request a specific connection priority. Must be one of CONNECTION_PRIORITY_BALANCED , BluetoothGatt#CONNECTION_PRIORITY_HIGH
or BluetoothGatt#CONNECTION_PRIORITY_LOW_POWER . |
Returns | |
---|---|
boolean |
Throws | |
---|---|
IllegalArgumentException |
If the parameters are outside of their specified range. |
public boolean requestMtu (int mtu)
Request an MTU size used for a given connection.
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
mtu |
int |
Returns | |
---|---|
boolean |
true, if the new MTU value has been requested successfully |
public boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, boolean enable)
Enable or disable notifications/indications for a given characteristic.
Once notifications are enabled for a characteristic, a
BluetoothGattCallback#onCharacteristicChanged
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
characteristic |
BluetoothGattCharacteristic : The characteristic for which to enable notifications |
enable |
boolean : Set to true to enable notifications/indications |
Returns | |
---|---|
boolean |
true, if the requested notification status was set successfully |
public void setPreferredPhy (int txPhy, int rxPhy, int phyOptions)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
txPhy |
int : preferred transmitter PHY. Bitwise OR of any of BluetoothDevice.PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , and BluetoothDevice.PHY_LE_CODED_MASK . |
rxPhy |
int : preferred receiver PHY. Bitwise OR of any of BluetoothDevice.PHY_LE_1M_MASK , BluetoothDevice#PHY_LE_2M_MASK , and 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 |
public boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)
Writes a given characteristic and its values to the associated remote device.
Once the write operation has been completed, the
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
characteristic |
BluetoothGattCharacteristic : Characteristic to write on the remote device |
Returns | |
---|---|
boolean |
true, if the write operation was initiated successfully |
public boolean writeDescriptor (BluetoothGattDescriptor descriptor)
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
Activity.requestPermissions(String[], int)
.
Requires Manifest.permission.BLUETOOTH_CONNECT
Parameters | |
---|---|
descriptor |
BluetoothGattDescriptor : Descriptor to write to the associated remote device |
Returns | |
---|---|
boolean |
true, if the write operation was initiated successfully |