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 {@link BluetoothGattCallback}
* and call {@link BluetoothDevice#connectGatt} to get a instance of this class.
* GATT capable devices can be discovered using the Bluetooth device discovery or BLE
* scan process.
*/
public final class BluetoothGatt implements BluetoothProfile {
private static final String TAG = "BluetoothGatt";
private static final boolean DBG = true;
private static final boolean VDBG = false;
@UnsupportedAppUsage
private IBluetoothGatt mService;
@UnsupportedAppUsage
private volatile BluetoothGattCallback mCallback;
private Handler mHandler;
@UnsupportedAppUsage
private int mClientIf;
private BluetoothDevice mDevice;
@UnsupportedAppUsage
private boolean mAutoConnect;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.P, trackingBug = 115609023)
private int mAuthRetryState;
private int mConnState;
private final Object mStateLock = new Object();
private final Object mDeviceBusyLock = new Object();
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private Boolean mDeviceBusy = false;
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
private int mTransport;
private int mPhy;
private boolean mOpportunistic;
private final AttributionSource mAttributionSource;
private static final int AUTH_RETRY_STATE_IDLE = 0;
private static final int AUTH_RETRY_STATE_NO_MITM = 1;
private static final int AUTH_RETRY_STATE_MITM = 2;
private static final int CONN_STATE_IDLE = 0;
private static final int CONN_STATE_CONNECTING = 1;
private static final int CONN_STATE_CONNECTED = 2;
private static final int CONN_STATE_DISCONNECTING = 3;
private static final int CONN_STATE_CLOSED = 4;
private static final int WRITE_CHARACTERISTIC_MAX_RETRIES = 5;
private static final int WRITE_CHARACTERISTIC_TIME_TO_WAIT = 10; // milliseconds
private List This is an asynchronous call. The callback {@link BluetoothGattCallback#onAppRegistered}
* is used to notify success or failure if the function returns true.
*
* @param callback GATT callback handler that will receive asynchronous callbacks.
* @return If true, the callback will be called to notify success or failure, false on immediate
* error
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
private boolean registerApp(BluetoothGattCallback callback, Handler handler) {
return registerApp(callback, handler, false);
}
/**
* Register an application callback to start using GATT.
*
* This is an asynchronous call. The callback {@link BluetoothGattCallback#onAppRegistered}
* is used to notify success or failure if the function returns true.
*
* @param callback GATT callback handler that will receive asynchronous callbacks.
* @param eatt_support indicate to allow for eatt support
* @return If true, the callback will be called to notify success or failure, false on immediate
* error
* @hide
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
private boolean registerApp(BluetoothGattCallback callback, Handler handler,
boolean eatt_support) {
if (DBG) Log.d(TAG, "registerApp()");
if (mService == null) return false;
mCallback = callback;
mHandler = handler;
UUID uuid = UUID.randomUUID();
if (DBG) Log.d(TAG, "registerApp() - UUID=" + uuid);
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.registerClient(new ParcelUuid(uuid), mBluetoothGattCallback, eatt_support,
mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Unregister the current application and callbacks.
*/
@UnsupportedAppUsage
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
private void unregisterApp() {
if (DBG) Log.d(TAG, "unregisterApp() - mClientIf=" + mClientIf);
if (mService == null || mClientIf == 0) return;
try {
mCallback = null;
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.unregisterClient(mClientIf, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
mClientIf = 0;
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
}
}
/**
* Initiate a connection to a Bluetooth GATT capable device.
*
* The connection may not be established right away, but will be
* completed when the remote device is available. A
* {@link BluetoothGattCallback#onConnectionStateChange} callback will be
* invoked when the connection state changes as a result of this function.
*
* The autoConnect parameter determines whether to actively connect to
* the remote device, or rather passively scan and finalize the connection
* when the remote device is in range/available. Generally, the first ever
* connection to a device should be direct (autoConnect set to false) and
* subsequent connections to known devices should be invoked with the
* autoConnect parameter set to true.
*
* @param device Remote device to connect to
* @param autoConnect Whether to directly connect to the remote device (false) or to
* automatically connect as soon as the remote device becomes available (true).
* @return true, if the connection attempt was initiated successfully
*/
@UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553)
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
/*package*/ boolean connect(Boolean autoConnect, BluetoothGattCallback callback,
Handler handler) {
if (DBG) {
Log.d(TAG,
"connect() - device: " + mDevice.getAddress() + ", auto: " + autoConnect);
}
synchronized (mStateLock) {
if (mConnState != CONN_STATE_IDLE) {
throw new IllegalStateException("Not idle");
}
mConnState = CONN_STATE_CONNECTING;
}
mAutoConnect = autoConnect;
if (!registerApp(callback, handler)) {
synchronized (mStateLock) {
mConnState = CONN_STATE_IDLE;
}
Log.e(TAG, "Failed to register callback");
return false;
}
// The connection will continue in the onClientRegistered callback
return true;
}
/**
* Disconnects an established connection, or cancels a connection attempt
* currently in progress.
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public void disconnect() {
if (DBG) Log.d(TAG, "cancelOpen() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.clientDisconnect(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
}
}
/**
* 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.
*
* @return true, if the connection attempt was initiated successfully
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean connect() {
try {
// autoConnect is inverse of "isDirect"
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.clientConnect(mClientIf, mDevice.getAddress(), false, mTransport,
mOpportunistic, mPhy, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
return true;
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
}
/**
* 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.
*
* {@link 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.
*
* @param txPhy preferred transmitter PHY. Bitwise OR of any of {@link
* BluetoothDevice#PHY_LE_1M_MASK}, {@link BluetoothDevice#PHY_LE_2M_MASK}, and {@link
* BluetoothDevice#PHY_LE_CODED_MASK}.
* @param rxPhy preferred receiver PHY. Bitwise OR of any of {@link
* BluetoothDevice#PHY_LE_1M_MASK}, {@link BluetoothDevice#PHY_LE_2M_MASK}, and {@link
* BluetoothDevice#PHY_LE_CODED_MASK}.
* @param phyOptions preferred coding to use when transmitting on the LE Coded PHY. Can be one
* of {@link BluetoothDevice#PHY_OPTION_NO_PREFERRED}, {@link BluetoothDevice#PHY_OPTION_S2} or
* {@link BluetoothDevice#PHY_OPTION_S8}
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public void setPreferredPhy(int txPhy, int rxPhy, int phyOptions) {
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.clientSetPreferredPhy(mClientIf, mDevice.getAddress(), txPhy, rxPhy,
phyOptions, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
}
}
/**
* Read the current transmitter PHY and receiver PHY of the connection. The values are returned
* in {@link BluetoothGattCallback#onPhyRead}
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public void readPhy() {
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.clientReadPhy(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
}
}
/**
* Return the remote bluetooth device this GATT client targets to
*
* @return remote bluetooth device
*/
@RequiresNoPermission
public BluetoothDevice getDevice() {
return mDevice;
}
/**
* 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 {@link BluetoothGattCallback#onServicesDiscovered} callback is
* triggered. If the discovery was successful, the remote services can be
* retrieved using the {@link #getServices} function.
*
* @return true, if the remote service discovery has been started
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean discoverServices() {
if (DBG) Log.d(TAG, "discoverServices() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
mServices.clear();
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.discoverServices(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Discovers a service by UUID. This is exposed only for passing PTS tests.
* It should never be used by real applications. The service is not searched
* for characteristics and descriptors, or returned in any callback.
*
* @return true, if the remote service discovery has been started
* @hide
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean discoverServiceByUuid(UUID uuid) {
if (DBG) Log.d(TAG, "discoverServiceByUuid() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
mServices.clear();
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.discoverServiceByUuid(mClientIf, mDevice.getAddress(), new ParcelUuid(uuid),
mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Returns a list of GATT services offered by the remote device.
*
* This function requires that service discovery has been completed
* for the given device.
*
* @return List of services on the remote device. Returns an empty list if service discovery has
* not yet been performed.
*/
@RequiresLegacyBluetoothPermission
@RequiresNoPermission
public List 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.
*
* @param uuid UUID of the requested service
* @return BluetoothGattService if supported, or null if the requested service is not offered by
* the remote device.
*/
@RequiresLegacyBluetoothPermission
@RequiresNoPermission
public BluetoothGattService getService(UUID uuid) {
for (BluetoothGattService service : mServices) {
if (service.getDevice().equals(mDevice) && service.getUuid().equals(uuid)) {
return service;
}
}
return null;
}
/**
* Reads the requested characteristic from the associated remote device.
*
* This is an asynchronous operation. The result of the read operation
* is reported by the {@link BluetoothGattCallback#onCharacteristicRead(BluetoothGatt,
* BluetoothGattCharacteristic, byte[], int)} callback.
*
* @param characteristic Characteristic to read from the remote device
* @return true, if the read operation was initiated successfully
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean readCharacteristic(BluetoothGattCharacteristic characteristic) {
if ((characteristic.getProperties() & BluetoothGattCharacteristic.PROPERTY_READ) == 0) {
return false;
}
if (VDBG) Log.d(TAG, "readCharacteristic() - uuid: " + characteristic.getUuid());
if (mService == null || mClientIf == 0) return false;
BluetoothGattService service = characteristic.getService();
if (service == null) return false;
BluetoothDevice device = service.getDevice();
if (device == null) return false;
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) return false;
mDeviceBusy = true;
}
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.readCharacteristic(mClientIf, device.getAddress(),
characteristic.getInstanceId(), AUTHENTICATION_NONE, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
synchronized (mDeviceBusyLock) {
mDeviceBusy = false;
}
return false;
}
return true;
}
/**
* Reads the characteristic using its UUID from the associated remote device.
*
* This is an asynchronous operation. The result of the read operation
* is reported by the {@link BluetoothGattCallback#onCharacteristicRead(BluetoothGatt,
* BluetoothGattCharacteristic, byte[], int)} callback.
*
* @param uuid UUID of characteristic to read from the remote device
* @return true, if the read operation was initiated successfully
* @hide
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean readUsingCharacteristicUuid(UUID uuid, int startHandle, int endHandle) {
if (VDBG) Log.d(TAG, "readUsingCharacteristicUuid() - uuid: " + uuid);
if (mService == null || mClientIf == 0) return false;
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) return false;
mDeviceBusy = true;
}
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.readUsingCharacteristicUuid(mClientIf, mDevice.getAddress(),
new ParcelUuid(uuid), startHandle, endHandle, AUTHENTICATION_NONE,
mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
synchronized (mDeviceBusyLock) {
mDeviceBusy = false;
}
return false;
}
return true;
}
/**
* Writes a given characteristic and its values to the associated remote device.
*
* Once the write operation has been completed, the
* {@link BluetoothGattCallback#onCharacteristicWrite} callback is invoked,
* reporting the result of the operation.
*
* @param characteristic Characteristic to write on the remote device
* @return true, if the write operation was initiated successfully
* @throws IllegalArgumentException if characteristic or its value are null
*
* @deprecated Use {@link BluetoothGatt#writeCharacteristic(BluetoothGattCharacteristic, byte[],
* int)} as this is not memory safe because it relies on a {@link BluetoothGattCharacteristic}
* object whose underlying fields are subject to change outside this method.
*/
@Deprecated
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean writeCharacteristic(BluetoothGattCharacteristic characteristic) {
try {
return writeCharacteristic(characteristic, characteristic.getValue(),
characteristic.getWriteType()) == BluetoothStatusCodes.SUCCESS;
} catch (Exception e) {
return false;
}
}
/** @hide */
@Retention(RetentionPolicy.SOURCE)
@IntDef(value = {
BluetoothStatusCodes.SUCCESS,
BluetoothStatusCodes.ERROR_MISSING_BLUETOOTH_CONNECT_PERMISSION,
BluetoothStatusCodes.ERROR_DEVICE_NOT_CONNECTED,
BluetoothStatusCodes.ERROR_PROFILE_SERVICE_NOT_BOUND,
BluetoothStatusCodes.ERROR_GATT_WRITE_NOT_ALLOWED,
BluetoothStatusCodes.ERROR_GATT_WRITE_REQUEST_BUSY,
BluetoothStatusCodes.ERROR_UNKNOWN
})
public @interface WriteOperationReturnValues{}
/**
* Writes a given characteristic and its values to the associated remote device.
*
* Once the write operation has been completed, the
* {@link BluetoothGattCallback#onCharacteristicWrite} callback is invoked,
* reporting the result of the operation.
*
* @param characteristic Characteristic to write on the remote device
* @return whether the characteristic was successfully written to
* @throws IllegalArgumentException if characteristic or value are null
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
@WriteOperationReturnValues
public int writeCharacteristic(@NonNull BluetoothGattCharacteristic characteristic,
@NonNull byte[] value, @WriteType int writeType) {
if (characteristic == null) {
throw new IllegalArgumentException("characteristic must not be null");
}
if (value == null) {
throw new IllegalArgumentException("value must not be null");
}
if (VDBG) Log.d(TAG, "writeCharacteristic() - uuid: " + characteristic.getUuid());
if ((characteristic.getProperties() & BluetoothGattCharacteristic.PROPERTY_WRITE) == 0
&& (characteristic.getProperties()
& BluetoothGattCharacteristic.PROPERTY_WRITE_NO_RESPONSE) == 0) {
return BluetoothStatusCodes.ERROR_GATT_WRITE_NOT_ALLOWED;
}
if (mService == null || mClientIf == 0) {
return BluetoothStatusCodes.ERROR_PROFILE_SERVICE_NOT_BOUND;
}
BluetoothGattService service = characteristic.getService();
if (service == null) {
throw new IllegalArgumentException("Characteristic must have a non-null service");
}
BluetoothDevice device = service.getDevice();
if (device == null) {
throw new IllegalArgumentException("Service must have a non-null device");
}
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) {
return BluetoothStatusCodes.ERROR_GATT_WRITE_REQUEST_BUSY;
}
mDeviceBusy = true;
}
int requestStatus = BluetoothStatusCodes.ERROR_UNKNOWN;
try {
for (int i = 0; i < WRITE_CHARACTERISTIC_MAX_RETRIES; i++) {
final SynchronousResultReceiver Once the read operation has been completed, the
* {@link BluetoothGattCallback#onDescriptorRead} callback is
* triggered, signaling the result of the operation.
*
* @param descriptor Descriptor value to read from the remote device
* @return true, if the read operation was initiated successfully
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean readDescriptor(BluetoothGattDescriptor descriptor) {
if (VDBG) Log.d(TAG, "readDescriptor() - uuid: " + descriptor.getUuid());
if (mService == null || mClientIf == 0) return false;
BluetoothGattCharacteristic characteristic = descriptor.getCharacteristic();
if (characteristic == null) return false;
BluetoothGattService service = characteristic.getService();
if (service == null) return false;
BluetoothDevice device = service.getDevice();
if (device == null) return false;
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) return false;
mDeviceBusy = true;
}
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.readDescriptor(mClientIf, device.getAddress(),
descriptor.getInstanceId(), AUTHENTICATION_NONE, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
synchronized (mDeviceBusyLock) {
mDeviceBusy = false;
}
return false;
}
return true;
}
/**
* Write the value of a given descriptor to the associated remote device.
*
* A {@link BluetoothGattCallback#onDescriptorWrite} callback is triggered to report the
* result of the write operation.
*
* @param descriptor Descriptor to write to the associated remote device
* @return true, if the write operation was initiated successfully
* @throws IllegalArgumentException if descriptor or its value are null
*
* @deprecated Use {@link BluetoothGatt#writeDescriptor(BluetoothGattDescriptor, byte[])} as
* this is not memory safe because it relies on a {@link BluetoothGattDescriptor} object
* whose underlying fields are subject to change outside this method.
*/
@Deprecated
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean writeDescriptor(BluetoothGattDescriptor descriptor) {
try {
return writeDescriptor(descriptor, descriptor.getValue())
== BluetoothStatusCodes.SUCCESS;
} catch (Exception e) {
return false;
}
}
/**
* Write the value of a given descriptor to the associated remote device.
*
* A {@link BluetoothGattCallback#onDescriptorWrite} callback is triggered to report the
* result of the write operation.
*
* @param descriptor Descriptor to write to the associated remote device
* @return true, if the write operation was initiated successfully
* @throws IllegalArgumentException if descriptor or value are null
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
@WriteOperationReturnValues
public int writeDescriptor(@NonNull BluetoothGattDescriptor descriptor,
@NonNull byte[] value) {
if (descriptor == null) {
throw new IllegalArgumentException("descriptor must not be null");
}
if (value == null) {
throw new IllegalArgumentException("value must not be null");
}
if (VDBG) Log.d(TAG, "writeDescriptor() - uuid: " + descriptor.getUuid());
if (mService == null || mClientIf == 0) {
return BluetoothStatusCodes.ERROR_PROFILE_SERVICE_NOT_BOUND;
}
BluetoothGattCharacteristic characteristic = descriptor.getCharacteristic();
if (characteristic == null) {
throw new IllegalArgumentException("Descriptor must have a non-null characteristic");
}
BluetoothGattService service = characteristic.getService();
if (service == null) {
throw new IllegalArgumentException("Characteristic must have a non-null service");
}
BluetoothDevice device = service.getDevice();
if (device == null) {
throw new IllegalArgumentException("Service must have a non-null device");
}
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) return BluetoothStatusCodes.ERROR_GATT_WRITE_REQUEST_BUSY;
mDeviceBusy = true;
}
try {
final SynchronousResultReceiver Once a reliable write transaction has been initiated, all calls
* to {@link #writeCharacteristic} are sent to the remote device for
* verification and queued up for atomic execution. The application will
* receive a {@link BluetoothGattCallback#onCharacteristicWrite} callback in response to every
* {@link #writeCharacteristic(BluetoothGattCharacteristic, byte[], int)} call and is
* responsible for verifying if the value has been transmitted accurately.
*
* After all characteristics have been queued up and verified,
* {@link #executeReliableWrite} will execute all writes. If a characteristic
* was not written correctly, calling {@link #abortReliableWrite} will
* cancel the current transaction without committing any values on the
* remote device.
*
* @return true, if the reliable write transaction has been initiated
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean beginReliableWrite() {
if (VDBG) Log.d(TAG, "beginReliableWrite() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.beginReliableWrite(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* 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 {@link BluetoothGattCallback#onReliableWriteCompleted} callback is
* invoked to indicate whether the transaction has been executed correctly.
*
* @return true, if the request to execute the transaction has been sent
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean executeReliableWrite() {
if (VDBG) Log.d(TAG, "executeReliableWrite() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
synchronized (mDeviceBusyLock) {
if (mDeviceBusy) return false;
mDeviceBusy = true;
}
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.endReliableWrite(mClientIf, mDevice.getAddress(), true, mAttributionSource,
recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
synchronized (mDeviceBusyLock) {
mDeviceBusy = false;
}
return false;
}
return true;
}
/**
* Cancels a reliable write transaction for a given device.
*
* Calling this function will discard all queued characteristic write
* operations for a given remote device.
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public void abortReliableWrite() {
if (VDBG) Log.d(TAG, "abortReliableWrite() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.endReliableWrite(mClientIf, mDevice.getAddress(), false, mAttributionSource,
recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
}
}
/**
* @deprecated Use {@link #abortReliableWrite()}
*/
@Deprecated
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public void abortReliableWrite(BluetoothDevice mDevice) {
abortReliableWrite();
}
/**
* Enable or disable notifications/indications for a given characteristic.
*
* Once notifications are enabled for a characteristic, a
* {@link BluetoothGattCallback#onCharacteristicChanged(BluetoothGatt,
* BluetoothGattCharacteristic, byte[])} callback will be triggered if the remote device
* indicates that the given characteristic has changed.
*
* @param characteristic The characteristic for which to enable notifications
* @param enable Set to true to enable notifications/indications
* @return true, if the requested notification status was set successfully
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean setCharacteristicNotification(BluetoothGattCharacteristic characteristic,
boolean enable) {
if (DBG) {
Log.d(TAG, "setCharacteristicNotification() - uuid: " + characteristic.getUuid()
+ " enable: " + enable);
}
if (mService == null || mClientIf == 0) return false;
BluetoothGattService service = characteristic.getService();
if (service == null) return false;
BluetoothDevice device = service.getDevice();
if (device == null) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.registerForNotification(mClientIf, device.getAddress(),
characteristic.getInstanceId(), enable, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Clears the internal cache and forces a refresh of the services from the
* remote device.
*
* @hide
*/
@UnsupportedAppUsage
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean refresh() {
if (DBG) Log.d(TAG, "refresh() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.refreshDevice(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Read the RSSI for a connected remote device.
*
* The {@link BluetoothGattCallback#onReadRemoteRssi} callback will be
* invoked when the RSSI value has been read.
*
* @return true, if the RSSI value has been requested successfully
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean readRemoteRssi() {
if (DBG) Log.d(TAG, "readRssi() - device: " + mDevice.getAddress());
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.readRemoteRssi(mClientIf, mDevice.getAddress(), mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* 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 {@link BluetoothGattCallback#onMtuChanged} callback will indicate
* whether this operation was successful.
*
* @return true, if the new MTU value has been requested successfully
*/
@RequiresLegacyBluetoothPermission
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean requestMtu(int mtu) {
if (DBG) {
Log.d(TAG, "configureMTU() - device: " + mDevice.getAddress()
+ " mtu: " + mtu);
}
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.configureMTU(mClientIf, mDevice.getAddress(), mtu, mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Request a connection parameter update.
*
* This function will send a connection parameter update request to the
* remote device.
*
* @param connectionPriority Request a specific connection priority. Must be one of {@link
* BluetoothGatt#CONNECTION_PRIORITY_BALANCED}, {@link BluetoothGatt#CONNECTION_PRIORITY_HIGH}
* or {@link BluetoothGatt#CONNECTION_PRIORITY_LOW_POWER}.
* @throws IllegalArgumentException If the parameters are outside of their specified range.
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean requestConnectionPriority(int connectionPriority) {
if (connectionPriority < CONNECTION_PRIORITY_BALANCED
|| connectionPriority > CONNECTION_PRIORITY_LOW_POWER) {
throw new IllegalArgumentException("connectionPriority not within valid range");
}
if (DBG) Log.d(TAG, "requestConnectionPriority() - params: " + connectionPriority);
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.connectionParameterUpdate(mClientIf, mDevice.getAddress(), connectionPriority,
mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* Request an LE connection parameter update.
*
* This function will send an LE connection parameters update request to the remote device.
*
* @return true, if the request is send to the Bluetooth stack.
* @hide
*/
@RequiresBluetoothConnectPermission
@RequiresPermission(android.Manifest.permission.BLUETOOTH_CONNECT)
public boolean requestLeConnectionUpdate(int minConnectionInterval, int maxConnectionInterval,
int slaveLatency, int supervisionTimeout,
int minConnectionEventLen, int maxConnectionEventLen) {
if (DBG) {
Log.d(TAG, "requestLeConnectionUpdate() - min=(" + minConnectionInterval
+ ")" + (1.25 * minConnectionInterval)
+ "msec, max=(" + maxConnectionInterval + ")"
+ (1.25 * maxConnectionInterval) + "msec, latency=" + slaveLatency
+ ", timeout=" + supervisionTimeout + "msec" + ", min_ce="
+ minConnectionEventLen + ", max_ce=" + maxConnectionEventLen);
}
if (mService == null || mClientIf == 0) return false;
try {
final SynchronousResultReceiver recv = SynchronousResultReceiver.get();
mService.leConnectionUpdate(mClientIf, mDevice.getAddress(),
minConnectionInterval, maxConnectionInterval,
slaveLatency, supervisionTimeout,
minConnectionEventLen, maxConnectionEventLen,
mAttributionSource, recv);
recv.awaitResultNoInterrupt(getSyncTimeout()).getValue(null);
} catch (RemoteException | TimeoutException e) {
Log.e(TAG, "", e);
return false;
}
return true;
}
/**
* @deprecated Not supported - please use {@link BluetoothManager#getConnectedDevices(int)}
* with {@link BluetoothProfile#GATT} as argument
* @throws UnsupportedOperationException
*/
@Override
@RequiresNoPermission
@Deprecated
public int getConnectionState(BluetoothDevice device) {
throw new UnsupportedOperationException("Use BluetoothManager#getConnectionState instead.");
}
/**
* @deprecated Not supported - please use {@link BluetoothManager#getConnectedDevices(int)}
* with {@link BluetoothProfile#GATT} as argument
*
* @throws UnsupportedOperationException
*/
@Override
@RequiresNoPermission
@Deprecated
public List