WLAN-Suche – Übersicht

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

WLAN-Suche

Der Scanvorgang umfasst drei Schritte:

  1. Registrieren Sie einen Broadcast-Listener für SCAN_RESULTS_AVAILABLE_ACTION. Er wird aufgerufen, wenn Suchanfragen abgeschlossen sind, und gibt den Status „Erfolgreich“ oder „Fehlgeschlagen“ zurück. Auf Geräten mit Android 10 (API-Level 29) und höher wird diese Übertragung für jeden vollständigen WLAN-Scan gesendet, der von der Plattform oder anderen Apps auf dem Gerät ausgeführt wird. Apps können alle Scanabschlüsse auf dem Gerät passiv über die Übertragung verfolgen, ohne selbst einen Scan auszuführen.

  2. Fordern Sie einen Scan an, indem Sie WifiManager.startScan() drücken. Prüfen Sie den Rückgabestatus der Methode, da der Aufruf aus einem der folgenden Gründe fehlschlagen kann:

    • Scananfragen werden möglicherweise gedrosselt, wenn zu viele Scans in kurzer Zeit ausgeführt werden.
    • Das Gerät ist inaktiv und das Scannen ist deaktiviert.
    • Die WLAN-Hardware meldet einen Scanfehler.

  3. Scanergebnisse abrufen mit WifiManager.getScanResults() Die zurückgegebenen Scanergebnisse sind die zuletzt aktualisierten Ergebnisse. Dies können Ergebnisse eines vorherigen Scans sein, wenn der aktuelle Scan nicht abgeschlossen oder nicht erfolgreich war. Das bedeutet, dass Sie möglicherweise ältere Scanergebnisse erhalten, wenn Sie diese Methode aufrufen, bevor Sie eine erfolgreiche SCAN_RESULTS_AVAILABLE_ACTION-Ausstrahlung erhalten.

Im folgenden Code wird gezeigt, wie diese Schritte implementiert werden:

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-Ebene 26) wurden Einschränkungen für Berechtigungen und die zulässige Häufigkeit von WLAN-Scans eingeführt.

Um die Netzwerkleistung, Sicherheit und Akkulaufzeit zu verbessern, wurden in Android 9 (API-Level 28) die Berechtigungsanforderungen verschärft und die Häufigkeit von WLAN-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 anrufende App keine dieser Berechtigungen hat, schlägt der Anruf mit SecurityException fehl.

Alternativ können Sie auf Geräten mit Android 8.0 (API-Ebene 26) und höher die CompanionDeviceManager verwenden, um im Namen Ihrer App nach Companion-Geräten in der Nähe zu suchen, ohne dass die Berechtigung zur Standortermittlung erforderlich ist. Weitere Informationen zu dieser Option finden Sie unter Kompanion-Gerät koppeln.

Android 9:

Damit ein Aufruf von WifiManager.startScan() erfolgreich ist, müssen alle der folgenden Bedingungen erfüllt sein:

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

Damit ein Aufruf von WifiManager.startScan() erfolgreich ist, müssen alle der folgenden Bedingungen erfüllt sein:

  • Wenn Ihre App auf das SDK von Android 10 (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 Berechtigung CHANGE_WIFI_STATE.
  • Die Standortdienste sind auf dem Gerät aktiviert (unter Einstellungen > Standort).

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

  • Wenn Ihre App auf das SDK von Android 10 (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 Berechtigung ACCESS_WIFI_STATE.
  • Die Standortdienste sind auf dem Gerät aktiviert (unter Einstellungen > Standort).

Wenn die anrufende App nicht alle diese Anforderungen erfüllt, schlägt der Anruf 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 App im Hintergrund kann einmal innerhalb von 30 Minuten gescannt werden.

Android 9:

Jede App im Vordergrund kann innerhalb von zwei Minuten viermal gescannt werden. So können in kurzer Zeit viele Scans durchgeführt werden.

Alle Apps im Hintergrund können zusammen einmal innerhalb von 30 Minuten gescannt werden.

Android 10 und höher:

Es gelten dieselben Drosselungslimits wie unter Android 9. Es gibt eine neue Entwickleroption, mit der die Drosselung für lokale Tests deaktiviert werden kann (unter Entwickleroptionen > Netzwerk > Drosselung von WLAN-Scans).