no.nordicsemi.android.support.v18.scanner

Class ScanSettings.Builder

java.lang.Object

no.nordicsemi.android.support.v18.scanner.ScanSettings.Builder

Enclosing class:

ScanSettings

public static final class ScanSettings.Builder
extends Object

Builder for ScanSettings.

Constructor Summary

Constructors

Constructor and Description
Builder()

Method Summary

Modifier and Type	Method and Description
ScanSettings	build() Build ScanSettings.
ScanSettings.Builder	setCallbackType(int callbackType) Set callback type for Bluetooth LE scan.
ScanSettings.Builder	setLegacy(boolean legacy) Set whether only legacy advertisements should be returned in scan results.
ScanSettings.Builder	setMatchMode(int matchMode) Set match mode for Bluetooth LE scan filters hardware match
ScanSettings.Builder	setMatchOptions(long deviceTimeoutMillis, long taskIntervalMillis) The match options are used when the callback type has been set to ScanSettings.CALLBACK_TYPE_FIRST_MATCH or ScanSettings.CALLBACK_TYPE_MATCH_LOST and hardware does not support those types.
ScanSettings.Builder	setNumOfMatches(int numOfMatches) Set the number of matches for Bluetooth LE scan filters hardware match.
ScanSettings.Builder	setPhy(int phy) Set the Physical Layer to use during this scan.
ScanSettings.Builder	setPowerSave(long scanInterval, long restInterval) Pre-Lollipop scanning requires a wakelock and the CPU cannot go to sleep.
ScanSettings.Builder	setReportDelay(long reportDelayMillis) Set report delay timestamp for Bluetooth LE scan.
ScanSettings.Builder	setScanMode(int scanMode) Set scan mode for Bluetooth LE scan.
ScanSettings.Builder	setUseHardwareBatchingIfSupported(boolean use) Some devices, for example Samsung S6 and S6 Edge with Lollipop, return always the same RSSI value for all devices if offloaded batching is used.
ScanSettings.Builder	setUseHardwareCallbackTypesIfSupported(boolean use) This method may be used when callback type is set to a value different than ScanSettings.CALLBACK_TYPE_ALL_MATCHES.
ScanSettings.Builder	setUseHardwareFilteringIfSupported(boolean use) Several phones may have some issues when it comes to offloaded filtering.

Methods inherited from class java.lang.Object

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

Constructor Detail

Builder

public Builder()

Method Detail

setScanMode

public ScanSettings.Builder setScanMode(int scanMode)

Set scan mode for Bluetooth LE scan.

ScanSettings.SCAN_MODE_OPPORTUNISTIC is supported on Android Marshmallow onwards. On Lollipop this mode will fall back ScanSettings.SCAN_MODE_LOW_POWER, which actually means that the library will start its own scan instead of relying on scans from other apps. This may have significant impact on battery usage.

On pre-Lollipop devices, the settings set by setPowerSave(long, long) will be used. By default, the intervals are the same as for ScanSettings.SCAN_MODE_LOW_POWER.

Parameters:

scanMode - The scan mode can be one of ScanSettings.SCAN_MODE_LOW_POWER, ScanSettings.SCAN_MODE_BALANCED, ScanSettings.SCAN_MODE_LOW_LATENCY or ScanSettings.SCAN_MODE_OPPORTUNISTIC.

Throws:

IllegalArgumentException - If the scanMode is invalid.

setCallbackType

public ScanSettings.Builder setCallbackType(int callbackType)

Set callback type for Bluetooth LE scan.

Parameters:

callbackType - The callback type flags for the scan.

Throws:

IllegalArgumentException - If the callbackType is invalid.

setReportDelay

public ScanSettings.Builder setReportDelay(long reportDelayMillis)

Set report delay timestamp for Bluetooth LE scan.

Parameters:

reportDelayMillis - Delay of report in milliseconds. Set to 0 to be notified of results immediately. Values > 0 causes the scan results to be queued up and delivered after the requested delay or when the internal buffers fill up.

For delays below 5000 ms (5 sec) the ScanCallback.onBatchScanResults(List) will be called in unreliable intervals, but starting from around 5000 the intervals get even.

Throws:

IllegalArgumentException - If reportDelayMillis < 0.

setNumOfMatches

public ScanSettings.Builder setNumOfMatches(int numOfMatches)

Set the number of matches for Bluetooth LE scan filters hardware match.

Parameters:

numOfMatches - The num of matches can be one of ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT or ScanSettings.MATCH_NUM_FEW_ADVERTISEMENT or ScanSettings.MATCH_NUM_MAX_ADVERTISEMENT

Throws:

IllegalArgumentException - If the matchMode is invalid.

setMatchMode

public ScanSettings.Builder setMatchMode(int matchMode)

Set match mode for Bluetooth LE scan filters hardware match

Parameters:

matchMode - The match mode can be one of ScanSettings.MATCH_MODE_AGGRESSIVE or ScanSettings.MATCH_MODE_STICKY

Throws:

IllegalArgumentException - If the matchMode is invalid.

setLegacy

public ScanSettings.Builder setLegacy(boolean legacy)

Set whether only legacy advertisements should be returned in scan results. Legacy advertisements include advertisements as specified by the Bluetooth core specification 4.2 and below. This is true by default for compatibility with older apps.

Parameters:

legacy - true if only legacy advertisements will be returned

setPhy

public ScanSettings.Builder setPhy(int phy)

Set the Physical Layer to use during this scan. This is used only if setLegacy(boolean) is set to false and only on Android 0reo or newer. BluetoothAdapter.isLeCodedPhySupported() may be used to check whether LE Coded phy is supported by calling BluetoothAdapter.isLeCodedPhySupported(). Selecting an unsupported phy will result in failure to start scan.

Parameters:

phy - Can be one of BluetoothDevice.PHY_LE_1M, BluetoothDevice.PHY_LE_CODED or ScanSettings.PHY_LE_ALL_SUPPORTED

setUseHardwareFilteringIfSupported

public ScanSettings.Builder setUseHardwareFilteringIfSupported(boolean use)

Several phones may have some issues when it comes to offloaded filtering. Even if it should be supported, it may not work as expected. It has been observed for example, that setting 2 filters with different devices addresses on Nexus 6 with Lollipop gives no callbacks if one or both devices advertise. See https://code.google.com/p/android/issues/detail?id=181561.

Parameters:

use - true to enable (default) hardware offload filtering. If false a compat software filtering will be used (uses much more resources).

setUseHardwareBatchingIfSupported

public ScanSettings.Builder setUseHardwareBatchingIfSupported(boolean use)

Some devices, for example Samsung S6 and S6 Edge with Lollipop, return always the same RSSI value for all devices if offloaded batching is used. Batching may also be emulated using a compat mechanism - a periodically called timer. Timer approach requires more resources but reports devices in constant delays and works on devices that does not support offloaded batching. In comparison, when setReportDelay(..) is called with parameter 1000 the standard, hardware triggered callback will be called every 1500ms +-200ms.

Parameters:

use - true to enable (default) hardware offloaded batching if they are supported. False to always use compat mechanism.

setUseHardwareCallbackTypesIfSupported

public ScanSettings.Builder setUseHardwareCallbackTypesIfSupported(boolean use)

This method may be used when callback type is set to a value different than ScanSettings.CALLBACK_TYPE_ALL_MATCHES. When disabled, the Scanner Compat itself will take care of reporting first match and match lost. The compat behaviour may differ from the one natively supported on Android Marshmallow or newer.

Also, in compat mode values set by setMatchMode(int) and setNumOfMatches(int) are ignored. Instead use setMatchOptions(long, long) to set timer options.

Parameters:

use - true to enable (default) the offloaded match reporting if hardware supports it, false to enable compat implementation.

setMatchOptions

public ScanSettings.Builder setMatchOptions(long deviceTimeoutMillis,
                                            long taskIntervalMillis)

The match options are used when the callback type has been set to ScanSettings.CALLBACK_TYPE_FIRST_MATCH or ScanSettings.CALLBACK_TYPE_MATCH_LOST and hardware does not support those types. In that case BluetoothLeScannerCompat starts a task that runs periodically and calls ScanCallback.onScanResult(int, ScanResult) with type ScanSettings.CALLBACK_TYPE_MATCH_LOST if a device has not been seen for at least given time.

Parameters:

deviceTimeoutMillis - the time required for the device to be recognized as lost (default ScanSettings.MATCH_LOST_DEVICE_TIMEOUT_DEFAULT).

taskIntervalMillis - the task interval (default ScanSettings.MATCH_LOST_TASK_INTERVAL_DEFAULT).

setPowerSave

public ScanSettings.Builder setPowerSave(long scanInterval,
                                         long restInterval)

Pre-Lollipop scanning requires a wakelock and the CPU cannot go to sleep. To conserve power we can optionally scan for a certain duration (scan interval) and then rest for a time before starting scanning again. Won't affect Lollipop or later devices.

Parameters:

scanInterval - interval in ms to scan at a time.

restInterval - interval to sleep for without scanning before scanning again for scanInterval.

build

public ScanSettings build()

Build ScanSettings.