WLAN-Suche – Übersicht

Mit den WLAN-Suchfunktionen der WifiManager API können Sie eine Liste der WLAN-Zugangspunkte abrufen, die vom Gerät aus sichtbar sind.

WLAN-Suche

Der Scanprozess besteht aus drei Schritten:

Broadcast-Listener registrieren für SCAN_RESULTS_AVAILABLE_ACTION, Dieser wird aufgerufen, wenn Scananfragen abgeschlossen sind, und gibt den Status „Erfolg“ oder „Fehler“ zurück. Auf Geräten mit Android 10 (API-Level 29) und höher wird dieser Broadcast für jeden vollständigen Wi-Fi-Scan gesendet, der auf dem Gerät von der Plattform oder anderen Apps ausgeführt wird. Apps können alle Scanabschlüsse auf dem Gerät passiv abhören, indem sie den Broadcast verwenden, ohne einen eigenen Scan auszuführen.
Scan anfordern mit WifiManager.startScan(). Prüfen Sie den Rückgabestatus der Methode, da der Aufruf aus einem der folgenden Gründe fehlschlagen kann:
- Scananfragen können aufgrund zu vieler Scans in kurzer Zeit gedrosselt werden.
- Das Gerät ist inaktiv und der Scan ist deaktiviert.
- Die Wi-Fi-Hardware meldet einen Scanfehler.
Scanergebnisse abrufen mit WifiManager.getScanResults(). Die zurückgegebenen Scanergebnisse sind die zuletzt aktualisierten Ergebnisse. Sie stammen möglicherweise von einem vorherigen Scan, wenn der aktuelle Scan noch nicht abgeschlossen oder erfolgreich war. Das bedeutet, dass Sie möglicherweise ältere Scanergebnisse erhalten, wenn Sie diese Methode aufrufen bevor Sie einen erfolgreichen SCAN_RESULTS_AVAILABLE_ACTION Broadcast erhalten.

Der folgende Code zeigt ein Beispiel für die Implementierung dieser Schritte:

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 ...
}

Einschränkungen

Mit Android 8.0 (API-Level 26) wurden Einschränkungen in Bezug auf Berechtigungen und die zulässige Häufigkeit von Wi-Fi-Scans eingeführt.

Zur Verbesserung der Netzwerkleistung, Sicherheit und Akkulaufzeit wurden mit Android 9 (API-Level 28) die Berechtigungsanforderungen verschärft und die Häufigkeit von Wi-Fi-Scans weiter eingeschränkt.

Berechtigungen

Android 8.0 und Android 8.1 :

Für einen erfolgreichen Aufruf von WifiManager.getScanResults() ist eine der folgenden Berechtigungen erforderlich:

Wenn die aufrufende App keine dieser Berechtigungen hat, schlägt der Aufruf mit einer SecurityException fehl.

Alternativ können Sie auf Geräten mit Android 8.0 (API-Level 26) und höher mit CompanionDeviceManager einen Scan von Companion-Geräten in der Nähe im Namen Ihrer App ausführen, ohne dass die Berechtigung zur Standortermittlung erforderlich ist. Weitere Informationen zu dieser Option finden Sie unter Companion-Geräte koppeln.

Android 9 :

Für einen erfolgreichen Aufruf von WifiManager.startScan() müssen alle der folgenden Bedingungen erfüllt sein:

Ihre App hat die ACCESS_FINE_LOCATION oder ACCESS_COARSE_LOCATION Berechtigung.
Ihre App hat die CHANGE_WIFI_STATE Berechtigung.
Die Standortdienste sind auf dem Gerät aktiviert (Einstellungen > Standort).

Android 10 (API-Level 29) und höher :

Für einen erfolgreichen Aufruf von WifiManager.startScan() müssen alle der folgenden Bedingungen erfüllt sein:

Wenn Ihre App auf das Android 10 SDK (API-Level 29) oder höher ausgerichtet ist, hat sie die ACCESS_FINE_LOCATION Berechtigung.
Wenn Ihre App auf ein SDK ausgerichtet ist, das niedriger als Android 10 (API-Level 29) ist, hat sie die Berechtigung ACCESS_COARSE_LOCATION oder ACCESS_FINE_LOCATION.
Ihre App hat die CHANGE_WIFI_STATE Berechtigung.
Die Standortdienste sind auf dem Gerät aktiviert (Einstellungen > Standort).

Damit WifiManager.getScanResults() erfolgreich aufgerufen werden kann, müssen alle der folgenden Bedingungen erfüllt sein:

Wenn Ihre App auf das Android 10 SDK (API-Level 29) oder höher ausgerichtet ist, hat sie die Berechtigung ACCESS_FINE_LOCATION.
Wenn Ihre App auf ein SDK ausgerichtet ist, das niedriger als Android 10 (API-Level 29) ist, hat sie die Berechtigung ACCESS_COARSE_LOCATION oder ACCESS_FINE_LOCATION.
Ihre App hat die ACCESS_WIFI_STATE Berechtigung.
Die Standortdienste sind auf dem Gerät aktiviert (Einstellungen > Standort).

Wenn die aufrufende App nicht alle diese Anforderungen erfüllt, schlägt der Aufruf mit einem SecurityException fehl.

Drosselung

Für die Häufigkeit von Scans mit WifiManager.startScan() gelten die folgenden Einschränkungen:

Android 8.0 und Android 8.1 :

Jede Hintergrund-App kann einmal in einem Zeitraum von 30 Minuten scannen.

Android 9 :

Jede App im Vordergrund kann viermal in einem Zeitraum von 2 Minuten scannen. So sind mehrere Scans in kurzer Zeit möglich.

Alle Hintergrund-Apps zusammen können einmal in einem Zeitraum von 30 Minuten scannen.

Android 10 und höher :

Es gelten dieselben Drosselungsgrenzen wie bei Android 9. Es gibt eine neue Entwickleroption mit der die Drosselung für lokale Tests deaktiviert werden kann (unter Entwickleroptionen > Netzwerk > Wi-Fi-Scan-Drosselung).