Android APIs
public final class

BluetoothGatt

extends Object
implements BluetoothProfile
java.lang.Object
   ↳ android.bluetooth.BluetoothGatt

Class Overview

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 connectGatt(Context, boolean, BluetoothGattCallback) to get a instance of this class. GATT capable devices can be discovered using the Bluetooth device discovery or BLE scan process.

Summary

Constants
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
[Expand]
Inherited Constants
From interface android.bluetooth.BluetoothProfile
Public Methods
void abortReliableWrite()
Cancels a reliable write transaction for a given device.
void abortReliableWrite(BluetoothDevice mDevice)
This method was deprecated in API level 19. Use abortReliableWrite()
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 getConnectedDevices(int) with GATT as argument
int getConnectionState(BluetoothDevice device)
Not supported - please use getConnectedDevices(int) with GATT as argument
BluetoothDevice getDevice()
Return the remote bluetooth device this GATT client targets to
List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states)
Not supported - please use getDevicesMatchingConnectionStates(int, int[]) with GATT as first argument
BluetoothGattService getService(UUID uuid)
Returns a BluetoothGattService, if the requested UUID is supported by the remote device.
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.
boolean readRemoteRssi()
Read the RSSI for a connected remote device.
boolean setCharacteristicNotification(BluetoothGattCharacteristic characteristic, boolean enable)
Enable or disable notifications/indications for a given characteristic.
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.
[Expand]
Inherited Methods
From class java.lang.Object
From interface android.bluetooth.BluetoothProfile

Constants

public static final int GATT_FAILURE

Added in API level 18

A GATT operation failed, errors other than the above

Constant Value: 257 (0x00000101)

public static final int GATT_INSUFFICIENT_AUTHENTICATION

Added in API level 18

Insufficient authentication for a given operation

Constant Value: 5 (0x00000005)

public static final int GATT_INSUFFICIENT_ENCRYPTION

Added in API level 18

Insufficient encryption for a given operation

Constant Value: 15 (0x0000000f)

public static final int GATT_INVALID_ATTRIBUTE_LENGTH

Added in API level 18

A write operation exceeds the maximum length of the attribute

Constant Value: 13 (0x0000000d)

public static final int GATT_INVALID_OFFSET

Added in API level 18

A read or write operation was requested with an invalid offset

Constant Value: 7 (0x00000007)

public static final int GATT_READ_NOT_PERMITTED

Added in API level 18

GATT read operation is not permitted

Constant Value: 2 (0x00000002)

public static final int GATT_REQUEST_NOT_SUPPORTED

Added in API level 18

The given request is not supported

Constant Value: 6 (0x00000006)

public static final int GATT_SUCCESS

Added in API level 18

A GATT operation completed successfully

Constant Value: 0 (0x00000000)

public static final int GATT_WRITE_NOT_PERMITTED

Added in API level 18

GATT write operation is not permitted

Constant Value: 3 (0x00000003)

Public Methods

public void abortReliableWrite ()

Added in API level 19

Cancels a reliable write transaction for a given device.

Calling this function will discard all queued characteristic write operations for a given remote device.

Requires BLUETOOTH permission.

public void abortReliableWrite (BluetoothDevice mDevice)

Added in API level 18

This method was deprecated in API level 19.
Use abortReliableWrite()

public boolean beginReliableWrite ()

Added in API level 18

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 onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) 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 commiting any values on the remote device.

Requires BLUETOOTH permission.

Returns
  • true, if the reliable write transaction has been initiated

public void close ()

Added in API level 18

Close this Bluetooth GATT client. Application should call this method as early as possible after it is done with this GATT client.

public boolean connect ()

Added in API level 18

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.

Returns
  • true, if the connection attempt was initiated successfully

public void disconnect ()

Added in API level 18

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

Requires BLUETOOTH permission.

public boolean discoverServices ()

Added in API level 18

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 onServicesDiscovered(BluetoothGatt, int) callback is triggered. If the discovery was successful, the remote services can be retrieved using the getServices() function.

Requires BLUETOOTH permission.

Returns
  • true, if the remote service discovery has been started

public boolean executeReliableWrite ()

Added in API level 18

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 onReliableWriteCompleted(BluetoothGatt, int) callback is invoked to indicate whether the transaction has been executed correctly.

Requires BLUETOOTH permission.

Returns
  • true, if the request to execute the transaction has been sent

public List<BluetoothDevice> getConnectedDevices ()

Added in API level 18

Not supported - please use getConnectedDevices(int) with GATT as argument

Returns
  • List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

public int getConnectionState (BluetoothDevice device)

Added in API level 18

Not supported - please use getConnectedDevices(int) with GATT as argument

Parameters
device Remote bluetooth device.
Returns
Throws
UnsupportedOperationException

public BluetoothDevice getDevice ()

Added in API level 18

Return the remote bluetooth device this GATT client targets to

Returns
  • remote bluetooth device

public List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)

Added in API level 18

Not supported - please use getDevicesMatchingConnectionStates(int, int[]) with GATT as first argument

Parameters
states Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING,
Returns
  • List of devices. The list will be empty on error.
Throws
UnsupportedOperationException

public BluetoothGattService getService (UUID uuid)

Added in API level 18

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.

Requires BLUETOOTH permission.

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

public List<BluetoothGattService> getServices ()

Added in API level 18

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

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

Requires BLUETOOTH permission.

Returns
  • List of services on the remote device. Returns an empty list if service discovery has not yet been performed.

public boolean readCharacteristic (BluetoothGattCharacteristic characteristic)

Added in API level 18

Reads the requested characteristic from the associated remote device.

This is an asynchronous operation. The result of the read operation is reported by the onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, int) callback.

Requires BLUETOOTH permission.

Parameters
characteristic Characteristic to read from the remote device
Returns
  • true, if the read operation was initiated successfully

public boolean readDescriptor (BluetoothGattDescriptor descriptor)

Added in API level 18

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

Once the read operation has been completed, the onDescriptorRead(BluetoothGatt, BluetoothGattDescriptor, int) callback is triggered, signaling the result of the operation.

Requires BLUETOOTH permission.

Parameters
descriptor Descriptor value to read from the remote device
Returns
  • true, if the read operation was initiated successfully

public boolean readRemoteRssi ()

Added in API level 18

Read the RSSI for a connected remote device.

The onReadRemoteRssi(BluetoothGatt, int, int) callback will be invoked when the RSSI value has been read.

Requires BLUETOOTH permission.

Returns
  • true, if the RSSI value has been requested successfully

public boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, boolean enable)

Added in API level 18

Enable or disable notifications/indications for a given characteristic.

Once notifications are enabled for a characteristic, a onCharacteristicChanged(BluetoothGatt, BluetoothGattCharacteristic) callback will be triggered if the remote device indicates that the given characteristic has changed.

Requires BLUETOOTH permission.

Parameters
characteristic The characteristic for which to enable notifications
enable Set to true to enable notifications/indications
Returns
  • true, if the requested notification status was set successfully

public boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)

Added in API level 18

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

Once the write operation has been completed, the onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int) callback is invoked, reporting the result of the operation.

Requires BLUETOOTH permission.

Parameters
characteristic Characteristic to write on the remote device
Returns
  • true, if the write operation was initiated successfully

public boolean writeDescriptor (BluetoothGattDescriptor descriptor)

Added in API level 18

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

A onDescriptorWrite(BluetoothGatt, BluetoothGattDescriptor, int) callback is triggered to report the result of the write operation.

Requires BLUETOOTH permission.

Parameters
descriptor Descriptor to write to the associated remote device
Returns
  • true, if the write operation was initiated successfully