Wi-Fi 扫描概述

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

Wi-Fi 扫描流程

扫描流程分三个步骤

  1. 注册广播监听器以用于 SCAN_RESULTS_AVAILABLE_ACTION,当扫描请求完成时会调用此监听器,并提供其成功/失败状态。对于运行 Android 10(API 级别 29)及更高版本的设备,此广播将针对平台或其他应用在设备上执行的任何完整 Wi-Fi 扫描发送。应用可以通过使用广播而无需发出自己的扫描来被动地监听设备上的所有扫描完成情况。

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

    • 在短时间内进行过多扫描可能会导致扫描请求被限流。
    • 设备处于空闲状态且扫描已禁用。
    • Wi-Fi 硬件报告扫描失败。
  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)引入了有关权限和允许的 Wi-Fi 扫描频率的限制。

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

权限

Android 8.0 和 Android 8.1

成功调用 WifiManager.getScanResults() 需要以下任何一个权限

如果调用应用不具有任何这些权限,则调用将失败并出现 SecurityException

或者,在运行 Android 8.0(API 级别 26)及更高版本的设备上,您可以使用 CompanionDeviceManager 代表您的应用扫描附近的配套设备,而无需位置权限。有关此选项的更多信息,请参阅 配套设备配对

Android 9

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

Android 10(API 级别 29)及更高版本

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

  • 如果您的应用以 Android 10(API 级别 29)SDK 或更高版本为目标,则您的应用具有 ACCESS_FINE_LOCATION 权限。
  • 如果您的应用以低于 Android 10(API 级别 29)的 SDK 为目标,则您的应用具有 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION 权限。
  • 您的应用具有 CHANGE_WIFI_STATE 权限。
  • 设备上已启用位置服务(在**设置 > 位置**下)。

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

  • 如果您的应用以 Android 10(API 级别 29)SDK 或更高版本为目标,则您的应用具有 ACCESS_FINE_LOCATION 权限。
  • 如果您的应用以低于 Android 10(API 级别 29)的 SDK 为目标,则您的应用具有 ACCESS_COARSE_LOCATIONACCESS_FINE_LOCATION 权限。
  • 您的应用具有 ACCESS_WIFI_STATE 权限。
  • 设备上已启用位置服务(在**设置 > 位置**下)。

如果调用应用不满足所有这些要求,则调用将失败并出现 SecurityException

限流

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

Android 8.0 和 Android 8.1

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

Android 9

每个前台应用可以在 2 分钟内扫描四次。这允许在短时间内进行突发扫描。

所有后台应用加起来可以在 30 分钟内扫描一次。

Android 10 及更高版本

适用于 Android 9 的相同限流限制仍然适用。有一个新的开发者选项可以切换关闭限流以进行本地测试(在**开发者选项 > 网络 > Wi-Fi 扫描限流**下)。