no.nordicsemi.android.support.v18.scanner

Class BluetoothLeScannerCompat

java.lang.Object

no.nordicsemi.android.support.v18.scanner.BluetoothLeScannerCompat

public abstract class BluetoothLeScannerCompat
extends Object

This class provides methods to perform scan related operations for Bluetooth LE devices. An application can scan for a particular type of Bluetooth LE devices using ScanFilter. It can also request different types of callbacks for delivering the result.

Use getScanner() to get an instance of the scanner.

Since version 1.3.0 of the Scanner Compar Library library, PendingIntentReceiver and ScannerService will be added to AndroidManifest whether the scanning with PendingIntent feature is used or not. The ScannerService is used to emulate such scanning on platforms before Oreo, while PendingIntentReceiver is used to translate from native ScanResult to compat ScanResult and apply additional filtering.

Note: Most of the scan methods here require Manifest.permission#BLUETOOTH_ADMIN permission.

See Also:

ScanFilter

Field Summary

Fields

Modifier and Type	Field and Description
static String	EXTRA_CALLBACK_TYPE Optional extra indicating the callback type, which will be one of CALLBACK_TYPE_* constants in ScanSettings.
static String	EXTRA_ERROR_CODE Optional extra indicating the error code, if any.
static String	EXTRA_LIST_SCAN_RESULT Extra containing a list of ScanResults.

Method Summary

Modifier and Type	Method and Description
abstract void	flushPendingScanResults(ScanCallback callback) Flush pending batch scan results stored in Bluetooth controller.
static BluetoothLeScannerCompat	getScanner() Returns the scanner compat object
void	startScan(List<ScanFilter> filters, ScanSettings settings, android.content.Context context, android.app.PendingIntent callbackIntent) Start Bluetooth LE scan using a PendingIntent.
void	startScan(List<ScanFilter> filters, ScanSettings settings, ScanCallback callback) Start Bluetooth LE scan.
void	startScan(List<ScanFilter> filters, ScanSettings settings, ScanCallback callback, android.os.Handler handler) Start Bluetooth LE scan.
void	startScan(ScanCallback callback) Start Bluetooth LE scan with default parameters and no filters.
void	stopScan(android.content.Context context, android.app.PendingIntent callbackIntent) Stops an ongoing Bluetooth LE scan.
void	stopScan(ScanCallback callback) Stops an ongoing Bluetooth LE scan.

Methods inherited from class java.lang.Object

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

Field Detail

EXTRA_LIST_SCAN_RESULT

public static final String EXTRA_LIST_SCAN_RESULT

Extra containing a list of ScanResults. It can have one or more results if there was no error. In case of error, EXTRA_ERROR_CODE will contain the error code and this extra will not be available.

See Also:

Constant Field Values

EXTRA_ERROR_CODE

public static final String EXTRA_ERROR_CODE

Optional extra indicating the error code, if any. The error code will be one of the SCAN_FAILED_* codes in ScanCallback.

See Also:

Constant Field Values

EXTRA_CALLBACK_TYPE

public static final String EXTRA_CALLBACK_TYPE

Optional extra indicating the callback type, which will be one of CALLBACK_TYPE_* constants in ScanSettings.

See Also:

ScanCallback.onScanResult(int, android.bluetooth.le.ScanResult), Constant Field Values

Method Detail

getScanner

public static BluetoothLeScannerCompat getScanner()

Returns the scanner compat object

Returns:

scanner implementation

startScan

public final void startScan(ScanCallback callback)

Start Bluetooth LE scan with default parameters and no filters. The scan results will be delivered through callback.

Requires Manifest.permission#BLUETOOTH_ADMIN permission. An app must hold ACCESS_FINE_LOCATION permission in order to get results.

Parameters:

callback - Callback used to deliver scan results.

Throws:

IllegalArgumentException - If callback is null.

startScan

public final void startScan(List<ScanFilter> filters,
                            ScanSettings settings,
                            ScanCallback callback)

Start Bluetooth LE scan. The scan results will be delivered through callback.

Requires Manifest.permission#BLUETOOTH_ADMIN permission. An app must hold ACCESS_FINE_LOCATION permission in order to get results.

Parameters:

filters - ScanFilters for finding exact BLE devices.

settings - Optional settings for the scan.

callback - Callback used to deliver scan results.

Throws:

IllegalArgumentException - If settings or callback is null.

startScan

public final void startScan(List<ScanFilter> filters,
                            ScanSettings settings,
                            ScanCallback callback,
                            android.os.Handler handler)

Start Bluetooth LE scan. The scan results will be delivered through callback.

Requires Manifest.permission#BLUETOOTH_ADMIN permission. An app must hold ACCESS_FINE_LOCATION permission in order to get results.

Parameters:

filters - ScanFilters for finding exact BLE devices.

settings - Optional settings for the scan.

callback - Callback used to deliver scan results.

handler - Optional handler used to deliver results.

Throws:

IllegalArgumentException - If settings or callback is null.

stopScan

public final void stopScan(ScanCallback callback)

Stops an ongoing Bluetooth LE scan.

Requires Manifest.permission#BLUETOOTH_ADMIN permission.

Parameters:

callback - The callback used to start scanning.

startScan

public final void startScan(List<ScanFilter> filters,
                            ScanSettings settings,
                            android.content.Context context,
                            android.app.PendingIntent callbackIntent)

Start Bluetooth LE scan using a PendingIntent. The scan results will be delivered via the PendingIntent. On platforms before Oreo this will start ScannerService which will scan in background using given settings.

This method of scanning is intended to work in background. Long running scanning may consume a lot of battery, so it is recommended to use low power mode in settings, offloaded filtering and batching. However, the library may emulate batching, filtering or callback types ScanSettings.CALLBACK_TYPE_FIRST_MATCH and ScanSettings.CALLBACK_TYPE_MATCH_LOST if they are not supported.

A PendingIntentReceiver and ScannerService will be added to AndroidManifest whether this feature is used or not.

Requires Manifest.permission#BLUETOOTH_ADMIN permission. An app must hold ACCESS_FINE_LOCATION permission in order to get results.

When the PendingIntent is delivered, the Intent passed to the receiver or activity will contain one or more of the extras EXTRA_CALLBACK_TYPE, EXTRA_ERROR_CODE and EXTRA_LIST_SCAN_RESULT to indicate the result of the scan.

Parameters:

filters - ScanFilters for finding exact BLE devices.

settings - Optional settings for the scan.

context - Context used to start ScannerService.

callbackIntent - The PendingIntent to deliver the result to.

Throws:

IllegalArgumentException - If settings or callback is null.

stopScan

public final void stopScan(android.content.Context context,
                           android.app.PendingIntent callbackIntent)

Stops an ongoing Bluetooth LE scan.

Requires Manifest.permission#BLUETOOTH_ADMIN permission.

Parameters:

context - Context used to stop ScannerService.

callbackIntent - The PendingIntent that was used to start the scan.

flushPendingScanResults

public abstract void flushPendingScanResults(ScanCallback callback)

Flush pending batch scan results stored in Bluetooth controller. This will return Bluetooth LE scan results batched on Bluetooth controller. Returns immediately, batch scan results data will be delivered through the callback.

Parameters:

callback - Callback of the Bluetooth LE Scan, it has to be the same instance as the one used to start scan.