# Print output for @column tags ?>
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:
Constants | |
---|---|
String |
EXTRA_CALLBACK_TYPE
Optional extra indicating the callback type, which will be one of
CALLBACK_TYPE_* constants in |
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 |
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 | |
---|---|
public static final String EXTRA_CALLBACK_TYPE
Optional extra indicating the callback type, which will be one of
CALLBACK_TYPE_* constants in ScanSettings
.
Constant Value: "android.bluetooth.le.extra.CALLBACK_TYPE"
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"
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 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. |
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 either the
Manifest.permission#ACCESS_FINE_LOCATION
permission or a strong assertion that you will never derive the
physical location of the device. You can make this assertion by
declaring usesPermissionFlags="neverForLocation"
on the
relevant <uses-permission>
manifest tag, but it 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:
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 either the
Manifest.permission#ACCESS_FINE_LOCATION
permission or a strong assertion that you will never derive the
physical location of the device. You can make this assertion by
declaring usesPermissionFlags="neverForLocation"
on the
relevant <uses-permission>
manifest tag, but it 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. |
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 filetered scanning by
using proper 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 either the
Manifest.permission#ACCESS_FINE_LOCATION
permission or a strong assertion that you will never derive the
physical location of the device. You can make this assertion by
declaring usesPermissionFlags="neverForLocation"
on the
relevant <uses-permission>
manifest tag, but it may
restrict the types of Bluetooth devices you can interact with.
Requires Manifest.permission.BLUETOOTH_SCAN
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. |
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
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. |