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 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.
Constants | |
|---|---|
int |
CONNECTION_PRIORITY_BALANCED
Connection paramter update - Use the connection paramters recommended by the Bluetooth SIG. |
int |
CONNECTION_PRIORITY_HIGH
Connection paramter update - Request a high priority, low latency connection. |
int |
CONNECTION_PRIORITY_LOW_POWER
Connection paramter 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
|
Public methods | |
|---|---|
void
|
abortReliableWrite(BluetoothDevice mDevice)
This method was deprecated
in API level 19.
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. |
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. |
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
| |
From
interface
android.bluetooth.BluetoothProfile
| |
int CONNECTION_PRIORITY_BALANCED
Connection paramter update - Use the connection paramters recommended by the Bluetooth SIG. This is the default value if no connection parameter update is requested.
Constant Value: 0 (0x00000000)
int CONNECTION_PRIORITY_HIGH
Connection paramter update - Request a high priority, low latency connection.
An application should only request high priority connection paramters to transfer
large amounts of data over LE quickly. Once the transfer is complete, the application
should request CONNECTION_PRIORITY_BALANCED connectoin parameters
to reduce energy use.
Constant Value: 1 (0x00000001)
int CONNECTION_PRIORITY_LOW_POWER
Connection paramter update - Request low power, reduced data rate connection parameters.
Constant Value: 2 (0x00000002)
int GATT_CONNECTION_CONGESTED
A remote device connection is congested.
Constant Value: 143 (0x0000008f)
int GATT_FAILURE
A GATT operation failed, errors other than the above
Constant Value: 257 (0x00000101)
int GATT_INSUFFICIENT_AUTHENTICATION
Insufficient authentication for a given operation
Constant Value: 5 (0x00000005)
int GATT_INSUFFICIENT_ENCRYPTION
Insufficient encryption for a given operation
Constant Value: 15 (0x0000000f)
int GATT_INVALID_ATTRIBUTE_LENGTH
A write operation exceeds the maximum length of the attribute
Constant Value: 13 (0x0000000d)
int GATT_INVALID_OFFSET
A read or write operation was requested with an invalid offset
Constant Value: 7 (0x00000007)
int GATT_READ_NOT_PERMITTED
GATT read operation is not permitted
Constant Value: 2 (0x00000002)
int GATT_REQUEST_NOT_SUPPORTED
The given request is not supported
Constant Value: 6 (0x00000006)
int GATT_SUCCESS
A GATT operation completed successfully
Constant Value: 0 (0x00000000)
int GATT_WRITE_NOT_PERMITTED
GATT write operation is not permitted
Constant Value: 3 (0x00000003)
void abortReliableWrite (BluetoothDevice mDevice)
This method was deprecated
in API level 19.
Use abortReliableWrite()
| Parameters | |
|---|---|
mDevice |
BluetoothDevice
|
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 BLUETOOTH permission.
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 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 | |
|---|---|
boolean |
true, if the reliable write transaction has been initiated |
void close ()
Close this Bluetooth GATT client. Application should call this method as early as possible after it is done with this GATT client.
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 |
void disconnect ()
Disconnects an established connection, or cancels a connection attempt currently in progress.
Requires BLUETOOTH permission.
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 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 | |
|---|---|
boolean |
true, if the remote service discovery has been started |
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 onReliableWriteCompleted(BluetoothGatt, int) callback is
invoked to indicate whether the transaction has been executed correctly.
Requires BLUETOOTH permission.
| Returns | |
|---|---|
boolean |
true, if the request to execute the transaction has been sent |
List<BluetoothDevice> getConnectedDevices ()
Not supported - please use getConnectedDevices(int)
with GATT as argument
| Returns | |
|---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
| Throws | |
|---|---|
UnsupportedOperationException |
|
int getConnectionState (BluetoothDevice device)
Not supported - please use getConnectedDevices(int)
with 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
|
| Throws | |
|---|---|
UnsupportedOperationException |
|
BluetoothDevice getDevice ()
Return the remote bluetooth device this GATT client targets to
| Returns | |
|---|---|
BluetoothDevice |
remote bluetooth device |
List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)
Not supported - please use
getDevicesMatchingConnectionStates(int, int[])
with GATT as first argument
| Parameters | |
|---|---|
states |
int:
Array of states. States can be one of
STATE_CONNECTED, STATE_CONNECTING,
STATE_DISCONNECTED, STATE_DISCONNECTING, |
| Returns | |
|---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
| Throws | |
|---|---|
UnsupportedOperationException |
|
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 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. |
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 BLUETOOTH permission.
| Returns | |
|---|---|
List<BluetoothGattService> |
List of services on the remote device. Returns an empty list if service discovery has not yet been performed. |
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 onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, int)
callback.
Requires BLUETOOTH permission.
| Parameters | |
|---|---|
characteristic |
BluetoothGattCharacteristic:
Characteristic to read from the remote device |
| Returns | |
|---|---|
boolean |
true, if the read operation was initiated successfully |
boolean readDescriptor (BluetoothGattDescriptor descriptor)
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 |
BluetoothGattDescriptor:
Descriptor value to read from the remote device |
| Returns | |
|---|---|
boolean |
true, if the read operation was initiated successfully |
boolean readRemoteRssi ()
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 | |
|---|---|
boolean |
true, if the RSSI value has been requested successfully |
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
CONNECTION_PRIORITY_BALANCED,
CONNECTION_PRIORITY_HIGH
or CONNECTION_PRIORITY_LOW_POWER. |
| Returns | |
|---|---|
boolean |
|
| Throws | |
|---|---|
IllegalArgumentException |
If the parameters are outside of their specified range. |
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 onMtuChanged(BluetoothGatt, int, int) callback will indicate
whether this operation was successful.
Requires BLUETOOTH permission.
| Parameters | |
|---|---|
mtu |
int
|
| Returns | |
|---|---|
boolean |
true, if the new MTU value has been requested successfully |
boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, boolean enable)
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 |
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 |
boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)
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 |
BluetoothGattCharacteristic:
Characteristic to write on the remote device |
| Returns | |
|---|---|
boolean |
true, if the write operation was initiated successfully |
boolean writeDescriptor (BluetoothGattDescriptor descriptor)
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 |
BluetoothGattDescriptor:
Descriptor to write to the associated remote device |
| Returns | |
|---|---|
boolean |
true, if the write operation was initiated successfully |
Developers