no.nordicsemi.android.ble

Class WaitForValueChangedRequest

java.lang.Object

no.nordicsemi.android.ble.Request

no.nordicsemi.android.ble.TimeoutableRequest

no.nordicsemi.android.ble.TimeoutableValueRequest<T>

no.nordicsemi.android.ble.AwaitingRequest<DataReceivedCallback>

no.nordicsemi.android.ble.WaitForValueChangedRequest

All Implemented Interfaces:

Operation

public final class WaitForValueChangedRequest
extends AwaitingRequest<DataReceivedCallback>
implements Operation

Field Summary

Fields inherited from class no.nordicsemi.android.ble.TimeoutableRequest

timeout

Fields inherited from class no.nordicsemi.android.ble.Request

handler, requestHandler

Method Summary

Modifier and Type	Method and Description
<E extends ProfileReadResponse> E	awaitValid(java.lang.Class<E> responseClass) Similar to #await(DataReceivedCallback), but if the response class extends ProfileReadResponse and the received response is invalid, an exception is thrown.
<E extends ProfileReadResponse> E	awaitValid(java.lang.Class<E> responseClass, long timeout) Deprecated. Use timeout(long) and awaitValid(Class) instead.
<E extends ProfileReadResponse> E	awaitValid(E response) Similar to TimeoutableValueRequest.await(Class), but if the response class extends ProfileReadResponse and the received response is invalid, an exception is thrown.
<E extends ProfileReadResponse> E	awaitValid(E response, long timeout) Deprecated. Use timeout(long) and #awaitValid(E) instead.
WaitForValueChangedRequest	before(BeforeCallback callback) Sets a callback that will be executed before the execution of this operation starts.
WaitForValueChangedRequest	done(SuccessCallback callback) Use to set a completion callback.
WaitForValueChangedRequest	fail(FailCallback callback) Use to set a callback that will be called in case the request has failed.
WaitForValueChangedRequest	filter(DataFilter filter) Sets a filter which allows to skip some incoming data.
WaitForValueChangedRequest	invalid(InvalidRequestCallback callback) Use to set a callback that will be called in case the request was invalid, for example called before the device was connected.
WaitForValueChangedRequest	merge(DataMerger merger) Adds a merger that will be used to merge multiple packets into a single Data.
WaitForValueChangedRequest	merge(DataMerger merger, ReadProgressCallback callback) Adds a merger that will be used to merge multiple packets into a single Data.
WaitForValueChangedRequest	setHandler(android.os.Handler handler) Sets the handler that will be used to invoke callbacks.
WaitForValueChangedRequest	timeout(long timeout) Sets the operation timeout.
WaitForValueChangedRequest	trigger(Operation trigger) Sets an optional request that is suppose to trigger the notification or indication.
WaitForValueChangedRequest	with(DataReceivedCallback callback) Sets the value callback.

Methods inherited from class no.nordicsemi.android.ble.AwaitingRequest

await

Methods inherited from class no.nordicsemi.android.ble.TimeoutableValueRequest

await, await, await

Methods inherited from class no.nordicsemi.android.ble.TimeoutableRequest

await, await, enqueue, enqueue

Methods inherited from class no.nordicsemi.android.ble.Request

createBond, newConnectionPriorityRequest, newDisableBatteryLevelNotificationsRequest, newDisableIndicationsRequest, newDisableNotificationsRequest, newEnableBatteryLevelNotificationsRequest, newEnableIndicationsRequest, newEnableNotificationsRequest, newMtuRequest, newReadBatteryLevelRequest, newReadPhyRequest, newReadRequest, newReadRequest, newReadRssiRequest, newRefreshCacheRequest, newSetPreferredPhyRequest, newSleepRequest, newWaitForIndicationRequest, newWaitForNotificationRequest, newWriteRequest, newWriteRequest, newWriteRequest, newWriteRequest, newWriteRequest, newWriteRequest, removeBond

Methods inherited from class java.lang.Object

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

Method Detail

setHandler

@NonNull
public WaitForValueChangedRequest setHandler(@NonNull
                                                       android.os.Handler handler)

Description copied from class: Request

Sets the handler that will be used to invoke callbacks. By default, the handler set in BleManager will be used.

Overrides:

setHandler in class TimeoutableRequest

Parameters:

handler - The handler to invoke callbacks for this request.

Returns:

The request.

timeout

@NonNull
public WaitForValueChangedRequest timeout(long timeout)

Description copied from class: TimeoutableRequest

Sets the operation timeout. When the timeout occurs, the request will fail with FailCallback.REASON_TIMEOUT.

Overrides:

timeout in class TimeoutableValueRequest<DataReceivedCallback>

Parameters:

timeout - the request timeout in milliseconds, 0 to disable timeout.

Returns:

the callback.

done

@NonNull
public WaitForValueChangedRequest done(@NonNull
                                                 SuccessCallback callback)

Description copied from class: Request

Use to set a completion callback. The callback will be invoked when the operation has finished successfully unless the request was executed synchronously, in which case this callback will be ignored.

Overrides:

done in class Request

Parameters:

callback - the callback.

Returns:

The request.

fail

@NonNull
public WaitForValueChangedRequest fail(@NonNull
                                                 FailCallback callback)

Description copied from class: Request

Use to set a callback that will be called in case the request has failed. If the target device wasn't set before executing this request (BleManager.connect(BluetoothDevice) was never called), the Request.invalid(InvalidRequestCallback) will be used instead, as the BluetoothDevice is not known.

This callback will be ignored if request was executed synchronously, in which case the error will be returned as an exception.

Overrides:

fail in class Request

Parameters:

callback - the callback.

Returns:

The request.

invalid

@NonNull
public WaitForValueChangedRequest invalid(@NonNull
                                                    InvalidRequestCallback callback)

Description copied from class: Request

Use to set a callback that will be called in case the request was invalid, for example called before the device was connected. This callback will be ignored if request was executed synchronously, in which case the error will be returned as an exception.

Overrides:

invalid in class Request

Parameters:

callback - the callback.

Returns:

The request.

before

@NonNull
public WaitForValueChangedRequest before(@NonNull
                                                   BeforeCallback callback)

Description copied from class: Request

Sets a callback that will be executed before the execution of this operation starts.

Overrides:

before in class Request

Parameters:

callback - the callback.

Returns:

The request.

with

@NonNull
public WaitForValueChangedRequest with(@NonNull
                                                 DataReceivedCallback callback)

Description copied from class: TimeoutableValueRequest

Sets the value callback. When the request is invoked synchronously, this callback will be ignored and the received value will be returned by the await(...) method;

Overrides:

with in class TimeoutableValueRequest<DataReceivedCallback>

Parameters:

callback - the callback.

Returns:

The request.

trigger

@NonNull
public WaitForValueChangedRequest trigger(@NonNull
                                                    Operation trigger)

Description copied from class: AwaitingRequest

Sets an optional request that is suppose to trigger the notification or indication. This is to ensure that the characteristic value won't change before the callback was set.

Overrides:

trigger in class AwaitingRequest<DataReceivedCallback>

Parameters:

trigger - the operation that triggers the notification, usually a write characteristic request that write some OP CODE.

Returns:

The request.

filter

@NonNull
public WaitForValueChangedRequest filter(@NonNull
                                                   DataFilter filter)

Sets a filter which allows to skip some incoming data.

Parameters:

filter - the data filter.

Returns:

The request.

merge

@NonNull
public WaitForValueChangedRequest merge(@NonNull
                                                  DataMerger merger)

Adds a merger that will be used to merge multiple packets into a single Data. The merger may modify each packet if necessary.

Returns:

The request.

merge

@NonNull
public WaitForValueChangedRequest merge(@NonNull
                                                  DataMerger merger,
                                                  @NonNull
                                                  ReadProgressCallback callback)

Adds a merger that will be used to merge multiple packets into a single Data. The merger may modify each packet if necessary.

Returns:

The request.

awaitValid

@NonNull
public <E extends ProfileReadResponse> E awaitValid(@NonNull
                                                              E response)
                                                       throws RequestFailedException,
                                                              InvalidDataException,
                                                              DeviceDisconnectedException,
                                                              BluetoothDisabledException,
                                                              InvalidRequestException,
                                                              java.lang.InterruptedException

Similar to TimeoutableValueRequest.await(Class), but if the response class extends ProfileReadResponse and the received response is invalid, an exception is thrown. This allows to keep all error handling in one place.

Type Parameters:

E - a response class that extends ProfileReadResponse.

Parameters:

response - the result object.

Returns:

Object with a valid response.

Throws:

java.lang.IllegalStateException - thrown when you try to call this method from the main (UI) thread.

java.lang.InterruptedException - thrown when the timeout occurred before the characteristic value has changed.

RequestFailedException - thrown when the trigger request has failed.

DeviceDisconnectedException - thrown when the device disconnected before the notification or indication was received.

BluetoothDisabledException - thrown when the Bluetooth adapter has been disabled.

InvalidRequestException - thrown when the request was called before the device was connected at least once (unknown device).

InvalidDataException - thrown when the received data were not valid (that is when ReadResponse.onDataReceived(BluetoothDevice, Data) failed to parse the data correctly and called ProfileReadResponse.onInvalidDataReceived(BluetoothDevice, Data)).

awaitValid

@NonNull
public <E extends ProfileReadResponse> E awaitValid(@NonNull
                                                              java.lang.Class<E> responseClass)
                                                       throws RequestFailedException,
                                                              InvalidDataException,
                                                              DeviceDisconnectedException,
                                                              BluetoothDisabledException,
                                                              InvalidRequestException,
                                                              java.lang.InterruptedException

Similar to #await(DataReceivedCallback), but if the response class extends ProfileReadResponse and the received response is invalid, an exception is thrown. This allows to keep all error handling in one place.

Type Parameters:

E - a response class that extends ProfileReadResponse.

Parameters:

responseClass - the result class. This class will be instantiate, therefore it has to have a default constructor.

Returns:

Object with a valid response.

Throws:

java.lang.IllegalStateException - thrown when you try to call this method from the main (UI) thread.

java.lang.InterruptedException - thrown when the timeout occurred before the characteristic value has changed.

java.lang.IllegalArgumentException - thrown when the response class could not be instantiated.

RequestFailedException - thrown when the trigger request has failed.

DeviceDisconnectedException - thrown when the device disconnected before the notification or indication was received.

BluetoothDisabledException - thrown when the Bluetooth adapter has been disabled.

InvalidRequestException - thrown when the request was called before the device was connected at least once (unknown device).

InvalidDataException - thrown when the received data were not valid (that is when ReadResponse.onDataReceived(BluetoothDevice, Data) failed to parse the data correctly and called ProfileReadResponse.onInvalidDataReceived(BluetoothDevice, Data)).

awaitValid

@NonNull
 @Deprecated
public <E extends ProfileReadResponse> E awaitValid(@NonNull
                                                                            java.lang.Class<E> responseClass,
                                                                            long timeout)
                                                                     throws java.lang.InterruptedException,
                                                                            InvalidDataException,
                                                                            RequestFailedException,
                                                                            DeviceDisconnectedException,
                                                                            BluetoothDisabledException,
                                                                            InvalidRequestException

Deprecated. Use timeout(long) and awaitValid(Class) instead.

Same as TimeoutableValueRequest.await(Class, long), but if received response is not valid, this method will thrown an exception.

Type Parameters:

E - a response class that extends ProfileReadResponse.

Parameters:

responseClass - the result class. This class will be instantiate, therefore it has to have a default constructor.

timeout - optional timeout in milliseconds.

Returns:

Object with a valid response.

Throws:

java.lang.IllegalStateException - thrown when you try to call this method from the main (UI) thread.

java.lang.InterruptedException - thrown when the timeout occurred before the characteristic value has changed.

java.lang.IllegalArgumentException - thrown when the response class could not be instantiated.

RequestFailedException - thrown when the trigger request has failed.

DeviceDisconnectedException - thrown when the device disconnected before the notification or indication was received.

BluetoothDisabledException - thrown when the Bluetooth adapter has been disabled.

InvalidRequestException - thrown when the request was called before the device was connected at least once (unknown device).

InvalidDataException - thrown when the received data were not valid (that is when ReadResponse.onDataReceived(BluetoothDevice, Data) failed to parse the data correctly and called ProfileReadResponse.onInvalidDataReceived(BluetoothDevice, Data)).

awaitValid

@NonNull
 @Deprecated
public <E extends ProfileReadResponse> E awaitValid(@NonNull
                                                                            E response,
                                                                            long timeout)
                                                                     throws java.lang.InterruptedException,
                                                                            InvalidDataException,
                                                                            DeviceDisconnectedException,
                                                                            RequestFailedException,
                                                                            BluetoothDisabledException,
                                                                            InvalidRequestException

Deprecated. Use timeout(long) and #awaitValid(E) instead.

Same as TimeoutableValueRequest.await(Object, long), but if received response is not valid, this method will thrown an exception.

Type Parameters:

E - a response class that extends ProfileReadResponse.

Parameters:

response - the result object.

timeout - optional timeout in milliseconds.

Returns:

Object with a valid response.

Throws:

java.lang.IllegalStateException - thrown when you try to call this method from the main (UI) thread.

java.lang.InterruptedException - thrown when the timeout occurred before the characteristic value has changed.

RequestFailedException - thrown when the trigger request has failed.

DeviceDisconnectedException - thrown when the device disconnected before the notification or indication was received.

BluetoothDisabledException - thrown when the Bluetooth adapter has been disabled.

InvalidRequestException - thrown when the request was called before the device was connected at least once (unknown device).

InvalidDataException - thrown when the received data were not valid (that is when ReadResponse.onDataReceived(BluetoothDevice, Data) failed to parse the data correctly and called ProfileReadResponse.onInvalidDataReceived(BluetoothDevice, Data)).