no.nordicsemi.android.ble

Class ConnectRequest

java.lang.Object

no.nordicsemi.android.ble.Request

no.nordicsemi.android.ble.TimeoutableRequest

no.nordicsemi.android.ble.ConnectRequest

public class ConnectRequest
extends TimeoutableRequest

The connect request is used to connect to a Bluetooth LE device. The request will end when the device gets connected, the connection timeouts, or an error occurs.

The done(SuccessCallback) callback will be called after the device is ready, that is when it is connected, the services were discovered, the required services were found and the initialization queue set in BleManagerHandler.initialize() is complete (without or with errors).

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
ConnectRequest	before(BeforeCallback callback) Sets a callback that will be executed before the execution of this operation starts.
ConnectRequest	done(SuccessCallback callback) Use to set a completion callback.
ConnectRequest	fail(FailCallback callback) Use to set a callback that will be called in case the request has failed.
android.bluetooth.BluetoothDevice	getDevice()
ConnectRequest	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.
ConnectRequest	retry(int count) Sets an optional retry count.
ConnectRequest	retry(int count, int delay) Sets an optional retry count and a delay that the process will wait before each connection attempt.
ConnectRequest	setHandler(android.os.Handler handler) Sets the handler that will be used to invoke callbacks.
ConnectRequest	timeout(long timeout) Sets the operation timeout.
ConnectRequest	useAutoConnect(boolean autoConnect) This method replaces the BleManager.shouldAutoConnect() method.
ConnectRequest	usePreferredPhy(int phy) Sets the preferred PHY used for connection.

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 ConnectRequest 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 ConnectRequest 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 TimeoutableRequest

Parameters:

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

Returns:

the callback.

done

@NonNull
public ConnectRequest done(@NonNull
                                     SuccessCallback callback)

Use to set a completion callback. The callback will be invoked when the operation has finished successfully unless TimeoutableRequest.await() or its variant was used, in which case this callback will be ignored.

The done callback will also be called when one or more of initialization requests has failed due to a reason other than disconnect event. This is because BleManagerCallbacks.onDeviceReady(BluetoothDevice) is called no matter if the requests succeeded, or not. Set failure callbacks to initialization requests to get information about failures.

Overrides:

done in class Request

Parameters:

callback - the callback.

Returns:

The request.

fail

@NonNull
public ConnectRequest 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 ConnectRequest 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 ConnectRequest 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.

retry

public ConnectRequest retry(int count)

Sets an optional retry count. The BleManager will do that many attempts to connect to the device in case of an error. The library will NOT retry if the device is not reachable, that is when the 30 sec. timeout occurs. In that case the app should scan before connecting, to make sure the target is in range.

Parameters:

count - how many times should the BleManager retry to connect.

Returns:

The request.

See Also:

retry(int, int)

retry

public ConnectRequest retry(int count,
                            int delay)

Sets an optional retry count and a delay that the process will wait before each connection attempt. The library will NOT retry if the device is not reachable, that is when the 30 sec. timeout occurs. In that case the app should scan before connecting, to make sure the target is in range.

Parameters:

count - how many times should the BleManager retry to connect.

delay - the delay between each connection attempt, in milliseconds. The real delay will be 200 ms longer than specified, as Object.clone() is estimated to last 200 ms.

Returns:

The request.

See Also:

retry(int)

useAutoConnect

public ConnectRequest useAutoConnect(boolean autoConnect)

This method replaces the BleManager.shouldAutoConnect() method.

Sets whether to connect to the remote device just once (false) or to add the address to white list of devices that will be automatically connect as soon as they become available (true). In the latter case, if Bluetooth adapter is enabled, Android scans periodically for devices from the white list and, if an advertising packet is received from such, it tries to connect to it. When the connection is lost, the system will keep trying to reconnect to it. If method is called with parameter set to true, and the connection to the device is lost, the BleManagerCallbacks.onLinkLossOccurred(BluetoothDevice) callback is called instead of BleManagerCallbacks.onDeviceDisconnected(BluetoothDevice).

This feature works much better on newer Android phone models and may have issues on older phones.

This method should only be used with bonded devices, as otherwise the device may change it's address. It will however work also with non-bonded devices with private static address. A connection attempt to a non-bonded device with private resolvable address will fail.

The first connection to a device will always be created with autoConnect flag to false (see BluetoothDevice.connectGatt(Context, boolean, BluetoothGattCallback)). This is to make it quick as the user most probably waits for a quick response. If autoConnect is used (true), the following connections will be done using BluetoothGatt.connect(), which forces the autoConnect parameter to true.

Parameters:

autoConnect - true to use autoConnect feature on the second and following connections. The first connection is always done with autoConnect parameter equal to false, to make it faster and allow to timeout it the device is unreachable. Default value is false.

Returns:

The request.

usePreferredPhy

public ConnectRequest usePreferredPhy(int phy)

Sets the preferred PHY used for connection. Th value should be a bitmask composed of PhyRequest.PHY_LE_1M_MASK, PhyRequest.PHY_LE_2M_MASK or PhyRequest.PHY_LE_CODED_MASK.

Different PHYs are available only on more recent devices with Android 8+. Check BluetoothAdapter.isLe2MPhySupported() and BluetoothAdapter.isLeCodedPhySupported() if required PHYs are supported by this Android device. The default PHY is PhyRequest.PHY_LE_1M_MASK.

Parameters:

phy - preferred PHY for connections to remote LE device. Bitwise OR of any of PhyRequest.PHY_LE_1M_MASK, PhyRequest.PHY_LE_2M_MASK, and PhyRequest.PHY_LE_CODED_MASK. This option does not take effect if autoConnect is set to true.

Returns:

The request.

getDevice

@NonNull
public android.bluetooth.BluetoothDevice getDevice()