# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Constants | Inherited Constants | Methods | Inherited Methods

# BluetoothGatt

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

## Summary

### 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
From interface `android.bluetooth.BluetoothProfile`
`int` | `A2DP` A2DP profile.
`String` | `EXTRA_PREVIOUS_STATE` Extra for the connection state intents of the individual profiles.
`String` | `EXTRA_STATE` Extra for the connection state intents of the individual profiles.
`int` | `GATT` GATT
`int` | `GATT_SERVER` GATT_SERVER
`int` | `HEADSET` Headset and Handsfree profile
`int` | `HEALTH` This constant is deprecated. Health Device Profile (HDP) and MCAP protocol are no longer used. New apps should use Bluetooth Low Energy based solutions such as `BluetoothGatt`, `BluetoothAdapter#listenUsingL2capChannel()`, or `BluetoothDevice#createL2capChannel(int)`
`int` | `HEARING_AID` Hearing Aid Device
`int` | `HID_DEVICE` HID Device
`int` | `SAP`
`int` | `STATE_CONNECTED` The profile is in connected state
`int` | `STATE_CONNECTING` The profile is in connecting state
`int` | `STATE_DISCONNECTED` The profile is in disconnected state
`int` | `STATE_DISCONNECTING` The profile is in disconnecting state

### Public methods
`void` | `abortReliableWrite(BluetoothDevice mDevice)` This method is deprecated. Use `abortReliableWrite()`
`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 `BluetoothManager#getConnectedDevices(int)` with `BluetoothProfile#GATT` as argument
`int` | `getConnectionState(BluetoothDevice device)` Not supported - please use `BluetoothManager#getConnectedDevices(int)` with `BluetoothProfile#GATT` as argument
`BluetoothDevice` | `getDevice()` Return the remote bluetooth device this GATT client targets to
`List<BluetoothDevice>` | `getDevicesMatchingConnectionStates(int[] states)` Not supported - please use `BluetoothManager#getDevicesMatchingConnectionStates(int, int[])` with `BluetoothProfile#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.
`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
From class `java.lang.Object`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.
From interface `android.bluetooth.BluetoothProfile`
`abstract List<BluetoothDevice>` | `getConnectedDevices()` Get connected devices for this specific profile.
`abstract int` | `getConnectionState(BluetoothDevice device)` Get the current connection state of the profile Requires `Manifest.permission.BLUETOOTH`
`abstract List<BluetoothDevice>` | `getDevicesMatchingConnectionStates(int[] states)` Get a list of devices that match any of the given connection states.

## Constants

### CONNECTION_PRIORITY_BALANCED

    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)

### CONNECTION_PRIORITY_HIGH

    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)

### CONNECTION_PRIORITY_LOW_POWER

    public static final int CONNECTION_PRIORITY_LOW_POWER

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

Constant Value: 2 (0x00000002)

### GATT_CONNECTION_CONGESTED

    public static final int GATT_CONNECTION_CONGESTED

A remote device connection is congested.

Constant Value: 143 (0x0000008f)

### GATT_FAILURE

    public static final int GATT_FAILURE

A GATT operation failed, errors other than the above

Constant Value: 257 (0x00000101)

### GATT_INSUFFICIENT_AUTHENTICATION

    public static final int GATT_INSUFFICIENT_AUTHENTICATION

Insufficient authentication for a given operation

Constant Value: 5 (0x00000005)

### GATT_INSUFFICIENT_ENCRYPTION

    public static final int GATT_INSUFFICIENT_ENCRYPTION

Insufficient encryption for a given operation

Constant Value: 15 (0x0000000f)

### GATT_INVALID_ATTRIBUTE_LENGTH

    public static final int GATT_INVALID_ATTRIBUTE_LENGTH

A write operation exceeds the maximum length of the attribute

Constant Value: 13 (0x0000000d)

### GATT_INVALID_OFFSET

    public static final int GATT_INVALID_OFFSET

A read or write operation was requested with an invalid offset

Constant Value: 7 (0x00000007)

### GATT_READ_NOT_PERMITTED

    public static final int GATT_READ_NOT_PERMITTED

GATT read operation is not permitted

Constant Value: 2 (0x00000002)

### GATT_REQUEST_NOT_SUPPORTED

    public static final int GATT_REQUEST_NOT_SUPPORTED

The given request is not supported

Constant Value: 6 (0x00000006)

### GATT_SUCCESS

    public static final int GATT_SUCCESS

A GATT operation completed successfully

Constant Value: 0 (0x00000000)

### GATT_WRITE_NOT_PERMITTED

    public static final int GATT_WRITE_NOT_PERMITTED

GATT write operation is not permitted

Constant Value: 3 (0x00000003)

## Public methods

### abortReliableWrite

    public void abortReliableWrite (BluetoothDevice mDevice)

This method is deprecated.
Use `abortReliableWrite()`

Parameters
`mDevice` | `BluetoothDevice`

### abortReliableWrite

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

### beginReliableWrite

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Returns
`boolean` | true, if the reliable write transaction has been initiated

### close

    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.

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

Returns
`boolean` | true, if the connection attempt was initiated successfully

### disconnect

    public void disconnect ()

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

Requires `Manifest.permission.BLUETOOTH` permission.

### discoverServices

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Returns
`boolean` | true, if the remote service discovery has been started

### executeReliableWrite

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Returns
`boolean` | true, if the request to execute the transaction has been sent

### getConnectedDevices

    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

### getConnectionState

    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

### getDevice

    public BluetoothDevice getDevice ()

Return the remote bluetooth device this GATT client targets to

Returns
`BluetoothDevice` | remote bluetooth device

### getDevicesMatchingConnectionStates

    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

### getService

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

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.

### getServices

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

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

### readCharacteristic

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Parameters
`characteristic` | `BluetoothGattCharacteristic`: Characteristic to read from the remote device

Returns
`boolean` | true, if the read operation was initiated successfully

### readDescriptor

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Parameters
`descriptor` | `BluetoothGattDescriptor`: Descriptor value to read from the remote device

Returns
`boolean` | true, if the read operation was initiated successfully

### readPhy

    public void readPhy ()

Read the current transmitter PHY and receiver PHY of the connection. The values are returned in `BluetoothGattCallback#onPhyRead`

### readRemoteRssi

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Returns
`boolean` | true, if the RSSI value has been requested successfully

### requestConnectionPriority

    public boolean requestConnectionPriority (int connectionPriority)

Request a connection parameter update.

This function will send a connection parameter update request to the remote device.

Parameters
`connectionPriority` | `int`: Request a specific connection priority. Must be one of `BluetoothGatt#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.

### requestMtu

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Parameters
`mtu` | `int`

Returns
`boolean` | true, if the new MTU value has been requested successfully

### setCharacteristicNotification

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

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

### setPreferredPhy

    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.

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`

### writeCharacteristic

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Parameters
`characteristic` | `BluetoothGattCharacteristic`: Characteristic to write on the remote device

Returns
`boolean` | true, if the write operation was initiated successfully

### writeDescriptor

    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.

Requires `Manifest.permission.BLUETOOTH` permission.

Parameters
`descriptor` | `BluetoothGattDescriptor`: Descriptor to write to the associated remote device

Returns
`boolean` | true, if the write operation was initiated successfully

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*