public final class BluetoothGatt extends Object implements BluetoothProfile
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(android.content.Context, boolean, android.bluetooth.BluetoothGattCallback)
to get a instance of this class.
GATT capable devices can be discovered using the Bluetooth device discovery or BLE
scan process.
BluetoothProfile.ServiceListener
Modifier and Type | Field and Description |
---|---|
static int |
CONNECTION_PRIORITY_BALANCED
Connection paramter update - Use the connection paramters recommended by the
Bluetooth SIG.
|
static int |
CONNECTION_PRIORITY_HIGH
Connection paramter update - Request a high priority, low latency connection.
|
static int |
CONNECTION_PRIORITY_LOW_POWER
Connection paramter update - Request low power, reduced data rate connection parameters.
|
static int |
GATT_CONNECTION_CONGESTED
A remote device connection is congested.
|
static int |
GATT_FAILURE
A GATT operation failed, errors other than the above
|
static int |
GATT_INSUFFICIENT_AUTHENTICATION
Insufficient authentication for a given operation
|
static int |
GATT_INSUFFICIENT_ENCRYPTION
Insufficient encryption for a given operation
|
static int |
GATT_INVALID_ATTRIBUTE_LENGTH
A write operation exceeds the maximum length of the attribute
|
static int |
GATT_INVALID_OFFSET
A read or write operation was requested with an invalid offset
|
static int |
GATT_READ_NOT_PERMITTED
GATT read operation is not permitted
|
static int |
GATT_REQUEST_NOT_SUPPORTED
The given request is not supported
|
static int |
GATT_SUCCESS
A GATT operation completed successfully
|
static int |
GATT_WRITE_NOT_PERMITTED
GATT write operation is not permitted
|
A2DP, A2DP_SINK, AVRCP_CONTROLLER, EXTRA_PREVIOUS_STATE, EXTRA_STATE, GATT, GATT_SERVER, HEADSET, HEADSET_CLIENT, HEALTH, INPUT_DEVICE, MAP, PAN, PBAP, PBAP_CLIENT, PRIORITY_AUTO_CONNECT, PRIORITY_OFF, PRIORITY_ON, PRIORITY_UNDEFINED, SAP, STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING
Modifier and Type | Method and Description |
---|---|
void |
abortReliableWrite()
Cancels a reliable write transaction for a given device.
|
void |
abortReliableWrite(BluetoothDevice mDevice)
Deprecated.
|
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.
|
boolean |
readRemoteRssi()
Read the RSSI for a connected remote device.
|
boolean |
refresh()
Clears the internal cache and forces a refresh of the services from the
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.
|
public static final int GATT_SUCCESS
public static final int GATT_READ_NOT_PERMITTED
public static final int GATT_WRITE_NOT_PERMITTED
public static final int GATT_INSUFFICIENT_AUTHENTICATION
public static final int GATT_REQUEST_NOT_SUPPORTED
public static final int GATT_INSUFFICIENT_ENCRYPTION
public static final int GATT_INVALID_OFFSET
public static final int GATT_INVALID_ATTRIBUTE_LENGTH
public static final int GATT_CONNECTION_CONGESTED
public static final int GATT_FAILURE
public static final int CONNECTION_PRIORITY_BALANCED
public static final int CONNECTION_PRIORITY_HIGH
CONNECTION_PRIORITY_BALANCED
connectoin parameters
to reduce energy use.public static final int CONNECTION_PRIORITY_LOW_POWER
public void close()
public void disconnect()
Requires android.Manifest.permission#BLUETOOTH
permission.
public boolean connect()
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.
public BluetoothDevice getDevice()
public boolean discoverServices()
This is an asynchronous operation. Once service discovery is completed,
the BluetoothGattCallback.onServicesDiscovered(android.bluetooth.BluetoothGatt, int)
callback is
triggered. If the discovery was successful, the remote services can be
retrieved using the getServices()
function.
Requires android.Manifest.permission#BLUETOOTH
permission.
public List<BluetoothGattService> getServices()
This function requires that service discovery has been completed for the given device.
Requires android.Manifest.permission#BLUETOOTH
permission.
public BluetoothGattService getService(UUID uuid)
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 android.Manifest.permission#BLUETOOTH
permission.
uuid
- UUID of the requested servicepublic boolean readCharacteristic(BluetoothGattCharacteristic characteristic)
This is an asynchronous operation. The result of the read operation
is reported by the BluetoothGattCallback.onCharacteristicRead(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattCharacteristic, int)
callback.
Requires android.Manifest.permission#BLUETOOTH
permission.
characteristic
- Characteristic to read from the remote devicepublic boolean writeCharacteristic(BluetoothGattCharacteristic characteristic)
Once the write operation has been completed, the
BluetoothGattCallback.onCharacteristicWrite(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattCharacteristic, int)
callback is invoked,
reporting the result of the operation.
Requires android.Manifest.permission#BLUETOOTH
permission.
characteristic
- Characteristic to write on the remote devicepublic boolean readDescriptor(BluetoothGattDescriptor descriptor)
Once the read operation has been completed, the
BluetoothGattCallback.onDescriptorRead(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattDescriptor, int)
callback is
triggered, signaling the result of the operation.
Requires android.Manifest.permission#BLUETOOTH
permission.
descriptor
- Descriptor value to read from the remote devicepublic boolean writeDescriptor(BluetoothGattDescriptor descriptor)
A BluetoothGattCallback.onDescriptorWrite(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattDescriptor, int)
callback is
triggered to report the result of the write operation.
Requires android.Manifest.permission#BLUETOOTH
permission.
descriptor
- Descriptor to write to the associated remote devicepublic boolean beginReliableWrite()
Once a reliable write transaction has been initiated, all calls
to writeCharacteristic(android.bluetooth.BluetoothGattCharacteristic)
are sent to the remote device for
verification and queued up for atomic execution. The application will
receive an BluetoothGattCallback.onCharacteristicWrite(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattCharacteristic, int)
callback
in response to every writeCharacteristic(android.bluetooth.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 android.Manifest.permission#BLUETOOTH
permission.
public boolean executeReliableWrite()
This function will commit all queued up characteristic write operations for a given remote device.
A BluetoothGattCallback.onReliableWriteCompleted(android.bluetooth.BluetoothGatt, int)
callback is
invoked to indicate whether the transaction has been executed correctly.
Requires android.Manifest.permission#BLUETOOTH
permission.
public void abortReliableWrite()
Calling this function will discard all queued characteristic write operations for a given remote device.
Requires android.Manifest.permission#BLUETOOTH
permission.
public void abortReliableWrite(BluetoothDevice mDevice)
abortReliableWrite()
public boolean setCharacteristicNotification(BluetoothGattCharacteristic characteristic, boolean enable)
Once notifications are enabled for a characteristic, a
BluetoothGattCallback.onCharacteristicChanged(android.bluetooth.BluetoothGatt, android.bluetooth.BluetoothGattCharacteristic)
callback will be
triggered if the remote device indicates that the given characteristic
has changed.
Requires android.Manifest.permission#BLUETOOTH
permission.
characteristic
- The characteristic for which to enable notificationsenable
- Set to true to enable notifications/indicationspublic boolean refresh()
public boolean readRemoteRssi()
The BluetoothGattCallback.onReadRemoteRssi(android.bluetooth.BluetoothGatt, int, int)
callback will be
invoked when the RSSI value has been read.
Requires android.Manifest.permission#BLUETOOTH
permission.
public boolean requestMtu(int mtu)
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(android.bluetooth.BluetoothGatt, int, int)
callback will indicate
whether this operation was successful.
Requires android.Manifest.permission#BLUETOOTH
permission.
public boolean requestConnectionPriority(int connectionPriority)
This function will send a connection parameter update request to the remote device.
connectionPriority
- Request a specific connection priority. Must be one of
CONNECTION_PRIORITY_BALANCED
,
CONNECTION_PRIORITY_HIGH
or CONNECTION_PRIORITY_LOW_POWER
.IllegalArgumentException
- If the parameters are outside of their
specified range.public int getConnectionState(BluetoothDevice device)
BluetoothManager.getConnectedDevices(int)
with BluetoothProfile.GATT
as argumentgetConnectionState
in interface BluetoothProfile
device
- Remote bluetooth device.BluetoothProfile.STATE_CONNECTED
, BluetoothProfile.STATE_CONNECTING
,
BluetoothProfile.STATE_DISCONNECTED
, BluetoothProfile.STATE_DISCONNECTING
UnsupportedOperationException
public List<BluetoothDevice> getConnectedDevices()
BluetoothManager.getConnectedDevices(int)
with BluetoothProfile.GATT
as argumentgetConnectedDevices
in interface BluetoothProfile
UnsupportedOperationException
public List<BluetoothDevice> getDevicesMatchingConnectionStates(int[] states)
BluetoothManager.getDevicesMatchingConnectionStates(int, int[])
with BluetoothProfile.GATT
as first argumentgetDevicesMatchingConnectionStates
in interface BluetoothProfile
states
- Array of states. States can be one of
BluetoothProfile.STATE_CONNECTED
, BluetoothProfile.STATE_CONNECTING
,
BluetoothProfile.STATE_DISCONNECTED
, BluetoothProfile.STATE_DISCONNECTING
,UnsupportedOperationException