WLAN 扫描功能概览

您可以使用 WifiManager API 提供的 WLAN 扫描功能来获取设备上可见的 WLAN 接入点列表。

WLAN 扫描流程

扫描流程分为三步:

  1. SCAN_RESULTS_AVAILABLE_ACTION 注册一个广播侦听器;系统会在完成扫描请求时调用此侦听器,提供其成功/失败状态。对于运行 Android 10 (API level 29) and higher 的设备,系统将针对平台或其他应用在设备上执行的所有完整 WLAN 扫描发送此广播。应用可以使用广播被动监听设备上所有扫描的完成情况,无需发出自己的扫描。

  2. 使用 WifiManager.startScan() 请求扫描。请务必检查方法的返回状态,因为调用可能因以下任一原因失败:

    • 由于短时间扫描过多,扫描请求可能遭到节流。
    • 设备处于空闲状态,扫描已禁用。
    • WLAN 硬件报告扫描失败。
  3. 使用 WifiManager.getScanResults() 获取扫描结果。系统返回的扫描结果为最近更新的结果,但如果当前扫描尚未完成或成功,则可能返回以前扫描的结果。也就是说,如果在收到成功的 SCAN_RESULTS_AVAILABLE_ACTION 广播前调用此方法,您可能会获得较旧的扫描结果。

以下代码提供了如何实现这些步骤的示例:

Kotlin

val wifiManager = context.getSystemService(Context.WIFI_SERVICE) as WifiManager

val wifiScanReceiver = object : BroadcastReceiver() {

  override fun onReceive(context: Context, intent: Intent) {
    val success = intent.getBooleanExtra(WifiManager.EXTRA_RESULTS_UPDATED, false)
    if (success) {
      scanSuccess()
    } else {
      scanFailure()
    }
  }
}

val intentFilter = IntentFilter()
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION)
context.registerReceiver(wifiScanReceiver, intentFilter)

val success = wifiManager.startScan()
if (!success) {
  // scan failure handling
  scanFailure()
}

....

private fun scanSuccess() {
  val results = wifiManager.scanResults
  ... use new scan results ...
}

private fun scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  val results = wifiManager.scanResults
  ... potentially use older scan results ...
}

Java

WifiManager wifiManager = (WifiManager)
                   context.getSystemService(Context.WIFI_SERVICE);

BroadcastReceiver wifiScanReceiver = new BroadcastReceiver() {
  @Override
  public void onReceive(Context c, Intent intent) {
    boolean success = intent.getBooleanExtra(
                       WifiManager.EXTRA_RESULTS_UPDATED, false);
    if (success) {
      scanSuccess();
    } else {
      // scan failure handling
      scanFailure();
    }
  }
};

IntentFilter intentFilter = new IntentFilter();
intentFilter.addAction(WifiManager.SCAN_RESULTS_AVAILABLE_ACTION);
context.registerReceiver(wifiScanReceiver, intentFilter);

boolean success = wifiManager.startScan();
if (!success) {
  // scan failure handling
  scanFailure();
}

....

private void scanSuccess() {
  List<ScanResult> results = wifiManager.getScanResults();
  ... use new scan results ...
}

private void scanFailure() {
  // handle failure: new scan did NOT succeed
  // consider using old scan results: these are the OLD results!
  List<ScanResult> results = wifiManager.getScanResults();
  ... potentially use older scan results ...
}

限制

Android 8.0(API 级别 26)引入了有关权限和 WLAN 扫描允许频率的限制。

为提高网络性能和安全性,延长电池续航时间,Android 9(API 级别 28)收紧了权限要求,并进一步限制 WLAN 扫描频率。

权限

Android 8.0 和 Android 8.1:

成功调用 WifiManager.getScanResults() 需要以下任意一项权限:

如果调用应用没有其中任意一项权限,则调用将失败,并显示 SecurityException

Android 9:

成功调用 WifiManager.startScan() 需要满足以下所有条件:

Android 10 (API level 29) and higher:

成功调用 WifiManager.startScan() 需要满足以下所有条件:

若要成功调用 WifiManager.getScanResults(),需确保满足以下所有条件:

  • 如果应用适配 Android 10 (API level 29) SDK 或更高版本,则应用需要拥有 ACCESS_FINE_LOCATION 权限。
  • 如果应用适配低于 Android 10 (API level 29) 的 SDK,则应用需要拥有 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION 权限。
  • 应用拥有 ACCESS_WIFI_STATE 权限。
  • 设备已启用位置服务 (Settings > Location)。

若要成功调用 WifiManager.getScanResults(),需确保满足以下所有条件:

如果调用应用无法满足上述所有要求,则调用将失败,并显示 SecurityException

节流

以下限制适用于使用 WifiManager.startScan() 的扫描频率。

Android 8.0 和 Android 8.1:

每个后台应用可以在 30 分钟内扫描一次。

Android 9:

每个前台应用可以在 2 分钟内扫描四次。这样便可在短时间内进行多次扫描。

所有后台应用组合可以在 30 分钟内扫描一次。

Android 10 及更高版本:

适用 Android 9 的节流限制。新增一个开发者选项,用户可以关闭节流功能以便进行本地测试(Developer Options > Networking > Wi-Fi scan throttling)。