您可以使用 WifiManager API 提供的 Wi-Fi 掃描功能,取得裝置顯示的 Wi-Fi 存取點清單。
Wi-Fi 掃描程序
掃描程序有三個步驟:
為
SCAN_RESULTS_AVAILABLE_ACTION
註冊廣播事件監聽器 (掃描要求完成時會呼叫),提供其成功/失敗狀態。對於搭載 Android 10 (API 級別 29) 以上版本的裝置,系統會傳送該廣播訊息,讓平台或其他應用程式對裝置上執行的所有 Wi-Fi 掃描作業傳送。應用程式可以使用廣播訊息,被動監聽裝置上的所有掃描完成,而不需要自行掃描。使用
WifiManager.startScan()
要求掃描。請務必查看方法的傳回狀態,因為呼叫可能會因為下列任一原因而失敗:- 掃描要求在短時間內的掃描次數過多,因此可能會受到限制。
- 裝置處於閒置狀態,而且掃描功能已停用。
- Wi-Fi 硬體會回報掃描失敗。
使用
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()
,必須滿足下列「所有」條件:
- 應用程式具備
ACCESS_FINE_LOCATION
或ACCESS_COARSE_LOCATION
權限。 - 您的應用程式具備
CHANGE_WIFI_STATE
權限。 - 裝置已啟用定位服務 (依序前往「設定」>「位置」)。
Android 10 (API 級別 29) 以上版本:
如要成功呼叫 WifiManager.startScan()
,必須滿足下列「所有」條件:
- 如果您的應用程式指定 Android 10 (API 級別 29) SDK 或以上版本,則應用程式擁有
ACCESS_FINE_LOCATION
權限。 - 如果應用程式指定的 SDK 版本低於 Android 10 (API 級別 29),應用程式即具備
ACCESS_COARSE_LOCATION
或ACCESS_FINE_LOCATION
權限。 - 您的應用程式具有
CHANGE_WIFI_STATE
權限。 - 裝置已啟用定位服務 (依序前往「設定」 >「位置」)。
如要成功呼叫 WifiManager.getScanResults()
,請務必滿足下列「所有」條件:
- 如果您的應用程式指定 Android 10 (API 級別 29) SDK 或以上版本,則應用程式具備
ACCESS_FINE_LOCATION
權限。 - 如果您的應用程式指定的 SDK 版本低於 Android 10 (API 級別 29),應用程式即具備
ACCESS_COARSE_LOCATION
或ACCESS_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 掃描節流」)。