no.nordicsemi.android.ble

Class BleManager.BleManagerGattCallback

java.lang.Object

no.nordicsemi.android.ble.BleManager.BleManagerGattCallback

Enclosing class:

BleManager

protected abstract static class BleManager.BleManagerGattCallback
extends java.lang.Object

The GATT Callback handler. An object of this class must be returned by BleManager.getGattCallback(). It is responsible for all GATT operations.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BleManagerGattCallback()

Method Summary

Modifier and Type	Method and Description
android.bluetooth.BluetoothDevice	getBluetoothDevice()
byte[]	getCharacteristicValue(android.bluetooth.BluetoothGattCharacteristic serverCharacteristic) Returns the value of the server characteristic.
byte[]	getDescriptorValue(android.bluetooth.BluetoothGattDescriptor serverDescriptor) Returns the value of the server descriptor.
protected java.util.Deque<Request>	initGatt(android.bluetooth.BluetoothGatt gatt) Deprecated. Use initialize() instead.
protected void	initialize() This method should set up the request queue needed to initialize the profile.
protected boolean	isOptionalServiceSupported(android.bluetooth.BluetoothGatt gatt) This method should return true when the gatt device supports the optional services.
protected abstract boolean	isRequiredServiceSupported(android.bluetooth.BluetoothGatt gatt) This method should return true when the gatt device supports the required services.
protected void	onBatteryValueReceived(android.bluetooth.BluetoothGatt gatt, int value) Deprecated. Use ReadRequest.with(DataReceivedCallback) and BatteryLevelDataCallback from BLE-Common-Library instead.
protected void	onCharacteristicIndicated(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattCharacteristic characteristic) Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.
protected void	onCharacteristicNotified(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattCharacteristic characteristic) Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.
protected void	onCharacteristicRead(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattCharacteristic characteristic) Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.
protected void	onCharacteristicWrite(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattCharacteristic characteristic) Deprecated. Use WriteRequest.done(SuccessCallback) instead.
protected void	onConnectionUpdated(android.bluetooth.BluetoothGatt gatt, int interval, int latency, int timeout) Deprecated. Use ConnectionPriorityRequest.with(ConnectionPriorityCallback) instead.
protected void	onDescriptorRead(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattDescriptor descriptor) Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.
protected void	onDescriptorWrite(android.bluetooth.BluetoothGatt gatt, android.bluetooth.BluetoothGattDescriptor descriptor) Deprecated. Use WriteRequest and SuccessCallback instead.
protected abstract void	onDeviceDisconnected() This method should nullify all services and characteristics of the device.
protected void	onDeviceReady() Called when the initialization queue is complete.
protected void	onManagerReady() Called each time the task queue gets cleared.
protected void	onMtuChanged(android.bluetooth.BluetoothGatt gatt, int mtu) Deprecated. Use MtuRequest.with(MtuCallback) instead.
protected void	onServerReady(android.bluetooth.BluetoothGattServer server) In this method the manager should get references to server characteristics and descriptors that will use.
void	post(java.lang.Runnable r)
void	postDelayed(java.lang.Runnable r, long delayMillis)
void	removeCallbacks(java.lang.Runnable r)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

BleManagerGattCallback

protected BleManagerGattCallback()

Method Detail

getBluetoothDevice

public android.bluetooth.BluetoothDevice getBluetoothDevice()

getCharacteristicValue

@Nullable
public final byte[] getCharacteristicValue(@NonNull
                                                      android.bluetooth.BluetoothGattCharacteristic serverCharacteristic)

Returns the value of the server characteristic. For characteristics that are not shared, the value may be different for each connected device.

Parameters:

serverCharacteristic - The characteristic to get value of.

Returns:

The value.

getDescriptorValue

@Nullable
public final byte[] getDescriptorValue(@NonNull
                                                  android.bluetooth.BluetoothGattDescriptor serverDescriptor)

Returns the value of the server descriptor. For descriptor that are not shared, the value may be different for each connected device.

Parameters:

serverDescriptor - The descriptor to get value of.

Returns:

The value.

post

public void post(@NonNull
                 java.lang.Runnable r)

postDelayed

public void postDelayed(@NonNull
                        java.lang.Runnable r,
                        long delayMillis)

removeCallbacks

public void removeCallbacks(@NonNull
                            java.lang.Runnable r)

isRequiredServiceSupported

protected abstract boolean isRequiredServiceSupported(@NonNull
                                                      android.bluetooth.BluetoothGatt gatt)

This method should return true when the gatt device supports the required services.

Parameters:

gatt - the gatt device with services discovered

Returns:

True when the device has the required service.

isOptionalServiceSupported

protected boolean isOptionalServiceSupported(@NonNull
                                             android.bluetooth.BluetoothGatt gatt)

This method should return true when the gatt device supports the optional services. The default implementation returns false.

Parameters:

gatt - the gatt device with services discovered

Returns:

True when the device has the optional service.

initGatt

@Deprecated
protected java.util.Deque<Request> initGatt(@NonNull
                                                         android.bluetooth.BluetoothGatt gatt)

Deprecated. Use initialize() instead.

This method should return a list of requests needed to initialize the profile. Enabling Service Change indications for bonded devices and reading the Battery Level value and enabling Battery Level notifications is handled before executing this queue. The queue should not have requests that are not available, e.g. should not read an optional service when it is not supported by the connected device.

This method is called when the services has been discovered and the device is supported (has required service).

Parameters:

gatt - the gatt device with services discovered

Returns:

The queue of requests.

initialize

protected void initialize()

This method should set up the request queue needed to initialize the profile. Enabling Service Change indications for bonded devices is handled before executing this queue. The queue may have requests that are not available, e.g. read an optional service when it is not supported by the connected device. Such call will trigger Request.fail(FailCallback).

This method is called from the main thread when the services has been discovered and the device is supported (has required service).

Remember to call Request.enqueue() for each request.

A sample initialization should look like this:

 @Override
 protected void initialize() {
    requestMtu(MTU)
       .with((device, mtu) -> {
           ...
       })
       .enqueue();
    setNotificationCallback(characteristic)
       .with((device, data) -> {
           ...
       });
    enableNotifications(characteristic)
       .done(device -> {
           ...
       })
       .fail((device, status) -> {
           ...
       })
       .enqueue();
 }
 

onServerReady

protected void onServerReady(@NonNull
                             android.bluetooth.BluetoothGattServer server)

In this method the manager should get references to server characteristics and descriptors that will use. The method is called after the service discovery of a remote device has finished and isRequiredServiceSupported(BluetoothGatt) returned true.

The references obtained in this method should be released in onDeviceDisconnected().

This method is called only when the server was set by BleManager.useServer(BleServerManager) and opened using BleServerManager.open().

Parameters:

server - The GATT Server instance. Use BluetoothGattServer.getService(UUID) to obtain service instance.

onDeviceReady

protected void onDeviceReady()

Called when the initialization queue is complete.

onManagerReady

protected void onManagerReady()

Called each time the task queue gets cleared.

onDeviceDisconnected

protected abstract void onDeviceDisconnected()

This method should nullify all services and characteristics of the device. It's called when the device is no longer connected, either due to user action or a link loss.

onCharacteristicRead

@Deprecated
protected void onCharacteristicRead(@NonNull
                                                 android.bluetooth.BluetoothGatt gatt,
                                                 @NonNull
                                                 android.bluetooth.BluetoothGattCharacteristic characteristic)

Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.

Callback reporting the result of a characteristic read operation.

Parameters:

gatt - GATT client

characteristic - Characteristic that was read from the associated remote device.

onCharacteristicWrite

@Deprecated
protected void onCharacteristicWrite(@NonNull
                                                  android.bluetooth.BluetoothGatt gatt,
                                                  @NonNull
                                                  android.bluetooth.BluetoothGattCharacteristic characteristic)

Deprecated. Use WriteRequest.done(SuccessCallback) instead.

Callback indicating the result of a characteristic write operation.

If this callback is invoked while a reliable write transaction is in progress, the value of the characteristic represents the value reported by the remote device. An application should compare this value to the desired value to be written. If the values don't match, the application must abort the reliable write transaction.

Parameters:

gatt - GATT client

characteristic - Characteristic that was written to the associated remote device.

onDescriptorRead

@Deprecated
protected void onDescriptorRead(@NonNull
                                             android.bluetooth.BluetoothGatt gatt,
                                             @NonNull
                                             android.bluetooth.BluetoothGattDescriptor descriptor)

Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.

Callback reporting the result of a descriptor read operation.

Parameters:

gatt - GATT client

descriptor - Descriptor that was read from the associated remote device.

onDescriptorWrite

@Deprecated
protected void onDescriptorWrite(@NonNull
                                              android.bluetooth.BluetoothGatt gatt,
                                              @NonNull
                                              android.bluetooth.BluetoothGattDescriptor descriptor)

Deprecated. Use WriteRequest and SuccessCallback instead.

Callback indicating the result of a descriptor write operation.

If this callback is invoked while a reliable write transaction is in progress, the value of the characteristic represents the value reported by the remote device. An application should compare this value to the desired value to be written. If the values don't match, the application must abort the reliable write transaction.

Parameters:

gatt - GATT client

descriptor - Descriptor that was written to the associated remote device.

onBatteryValueReceived

@Deprecated
protected void onBatteryValueReceived(@NonNull
                                                   android.bluetooth.BluetoothGatt gatt,
                                                   int value)

Deprecated. Use ReadRequest.with(DataReceivedCallback) and BatteryLevelDataCallback from BLE-Common-Library instead.

Callback reporting the value of Battery Level characteristic which could have been received by Read or Notify operations.

This method will not be called if BleManager.readBatteryLevel() and BleManager.enableBatteryLevelNotifications() were overridden.

Parameters:

gatt - GATT client

value - the battery value in percent

onCharacteristicNotified

@Deprecated
protected void onCharacteristicNotified(@NonNull
                                                     android.bluetooth.BluetoothGatt gatt,
                                                     @NonNull
                                                     android.bluetooth.BluetoothGattCharacteristic characteristic)

Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.

Callback indicating a notification has been received.

Parameters:

gatt - GATT client

characteristic - Characteristic from which the notification came.

onCharacteristicIndicated

@Deprecated
protected void onCharacteristicIndicated(@NonNull
                                                      android.bluetooth.BluetoothGatt gatt,
                                                      @NonNull
                                                      android.bluetooth.BluetoothGattCharacteristic characteristic)

Deprecated. Use ReadRequest.with(DataReceivedCallback) instead.

Callback indicating an indication has been received.

Parameters:

gatt - GATT client

characteristic - Characteristic from which the indication came.

onMtuChanged

@Deprecated
protected void onMtuChanged(@NonNull
                                         android.bluetooth.BluetoothGatt gatt,
                                         int mtu)

Deprecated. Use MtuRequest.with(MtuCallback) instead.

Method called when the MTU request has finished with success. The MTU value may be different than requested one.

Parameters:

gatt - GATT client

mtu - the new MTU (Maximum Transfer Unit)

onConnectionUpdated

@Deprecated
protected void onConnectionUpdated(@NonNull
                                                android.bluetooth.BluetoothGatt gatt,
                                                int interval,
                                                int latency,
                                                int timeout)

Deprecated. Use ConnectionPriorityRequest.with(ConnectionPriorityCallback) instead.

Callback indicating the connection parameters were updated. Works on Android 8+.

Parameters:

gatt - GATT client.

interval - Connection interval used on this connection, 1.25ms unit. Valid range is from 6 (7.5ms) to 3200 (4000ms).

latency - Slave latency for the connection in number of connection events. Valid range is from 0 to 499.

timeout - Supervision timeout for this connection, in 10ms unit. Valid range is from 10 (0.1s) to 3200 (32s).