Added in API level 21

Summary: Constants | Methods | Inherited Methods

BluetoothLeScanner

Kotlin |Java

public final class BluetoothLeScanner
extends Object

java.lang.Object
↳	android.bluetooth.le.BluetoothLeScanner

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 BluetoothAdapter.getBluetoothLeScanner() to get an instance of BluetoothLeScanner.

See also:

ScanFilter

Summary

Constants
`String`	`EXTRA_CALLBACK_TYPE` Optional extra indicating the callback type, which will be one of CALLBACK_TYPE_* constants in `ScanSettings`.
`String`	`EXTRA_ERROR_CODE` Optional extra indicating the error code, if any.
`String`	`EXTRA_LIST_SCAN_RESULT` Extra containing a list of ScanResults.

Public methods
`void`	`flushPendingScanResults(ScanCallback callback)` Flush pending batch scan results stored in Bluetooth controller.
`int`	`startScan(List<ScanFilter> filters, ScanSettings settings, PendingIntent callbackIntent)` Start Bluetooth LE scan using a `PendingIntent`.
`void`	`startScan(ScanCallback callback)` Start Bluetooth LE scan with default parameters and no filters.
`void`	`startScan(List<ScanFilter> filters, ScanSettings settings, ScanCallback callback)` Start Bluetooth LE scan.
`void`	`stopScan(ScanCallback callback)` Stops an ongoing Bluetooth LE scan.
`void`	`stopScan(PendingIntent callbackIntent)` Stops an ongoing Bluetooth LE scan started using a PendingIntent.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

EXTRA_CALLBACK_TYPE

Added in API level 26

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, ScanResult)

Constant Value: "android.bluetooth.le.extra.CALLBACK_TYPE"

EXTRA_ERROR_CODE

Added in API level 26

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.

Constant Value: "android.bluetooth.le.extra.ERROR_CODE"

EXTRA_LIST_SCAN_RESULT

Added in API level 26

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.

Constant Value: "android.bluetooth.le.extra.LIST_SCAN_RESULT"

Public methods

flushPendingScanResults

Added in API level 21

public 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.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH_ADMIN permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_SCAN permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_SCAN

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

startScan

Added in API level 26

public int startScan (List<ScanFilter> filters, 
                ScanSettings settings, 
                PendingIntent callbackIntent)

Start Bluetooth LE scan using a PendingIntent. The scan results will be delivered via the PendingIntent. Use this method of scanning if your process is not always running and it should be started when scan results are available.

An app must have ACCESS_COARSE_LOCATION permission in order to get results. An App targeting Android Q or later must have 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.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH_ADMIN permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_SCAN permission which can be gained with Activity.requestPermissions(String[], int).
In addition, this requires the Manifest.permission.ACCESS_FINE_LOCATION permission. For apps targeting ERROR(/Build.VERSION_CODES#S) or higher, an alternative is a strong assertion that you will never derive the physical location of the device, made by declaring usesPermissionFlags="neverForLocation" on the relevant <uses-permission> manifest tag. However, this assertion may restrict the types of Bluetooth devices you can interact with.
Requires Manifest.permission.BLUETOOTH_SCAN

Parameters
`filters`	`List`: Optional list of ScanFilters for finding exact BLE devices. This value may be `null`.
`settings`	`ScanSettings`: Optional settings for the scan. This value may be `null`.
`callbackIntent`	`PendingIntent`: The PendingIntent to deliver the result to. This value cannot be `null`.

Returns
`int`	Returns 0 for success or an error code from `ScanCallback` if the scan request could not be sent.

See also:

stopScan(PendingIntent)

startScan

Added in API level 21

public void startScan (ScanCallback callback)

Start Bluetooth LE scan with default parameters and no filters. The scan results will be delivered through callback. For unfiltered scans, scanning is stopped on screen off to save power. Scanning is resumed when screen is turned on again. To avoid this, use startScan(java.util.List, android.bluetooth.le.ScanSettings, android.bluetooth.le.ScanCallback) with desired ScanFilter.

An app must have ACCESS_COARSE_LOCATION permission in order to get results. An App targeting Android Q or later must have ACCESS_FINE_LOCATION permission in order to get results.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH_ADMIN permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_SCAN permission which can be gained with Activity.requestPermissions(String[], int).
In addition, this requires the Manifest.permission.ACCESS_FINE_LOCATION permission. For apps targeting ERROR(/Build.VERSION_CODES#S) or higher, an alternative is a strong assertion that you will never derive the physical location of the device, made by declaring usesPermissionFlags="neverForLocation" on the relevant <uses-permission> manifest tag. However, this assertion may restrict the types of Bluetooth devices you can interact with.
Requires Manifest.permission.BLUETOOTH_SCAN

Parameters
`callback`	`ScanCallback`: Callback used to deliver scan results.

Throws
`IllegalArgumentException`	If `callback` is null.

startScan

Added in API level 21

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

Start Bluetooth LE scan. The scan results will be delivered through callback. For unfiltered scans, scanning is stopped on screen off to save power. Scanning is resumed when screen is turned on again. To avoid this, do filtered scanning by using proper ScanFilter.

Parameters
`filters`	`List`: `ScanFilter`s for finding exact BLE devices.
`settings`	`ScanSettings`: Settings for the scan.
`callback`	`ScanCallback`: Callback used to deliver scan results.

Throws
`IllegalArgumentException`	If `settings` or `callback` is null.

stopScan

Added in API level 21

public void stopScan (ScanCallback callback)

Stops an ongoing Bluetooth LE scan.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH_ADMIN permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_SCAN permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_SCAN

Parameters
`callback`	`ScanCallback`

stopScan

Added in API level 26

public void stopScan (PendingIntent callbackIntent)

Stops an ongoing Bluetooth LE scan started using a PendingIntent. When creating the PendingIntent parameter, please do not use the FLAG_CANCEL_CURRENT flag. Otherwise, the stop scan may have no effect.
For apps targeting Build.VERSION_CODES.R or lower, this requires the Manifest.permission.BLUETOOTH_ADMIN permission which can be gained with a simple <uses-permission> manifest tag.
For apps targeting Build.VERSION_CODES.S or or higher, this requires the Manifest.permission.BLUETOOTH_SCAN permission which can be gained with Activity.requestPermissions(String[], int).
Requires Manifest.permission.BLUETOOTH_SCAN

Parameters
`callbackIntent`	`PendingIntent`: The PendingIntent that was used to start the scan.

See also:

startScan(List, ScanSettings, PendingIntent)