Diese Seite wurde von der Cloud Translation API übersetzt.

WLAN-Suche – Übersicht

Sie können die WLAN-Suchfunktionen der WifiManager API verwenden, um eine Liste der WLAN-Zugangspunkte abzurufen, die auf dem Gerät sichtbar sind.

WLAN-Suche

Der Scanvorgang besteht aus drei Schritten:

Registrieren Sie einen Broadcast-Listener für SCAN_RESULTS_AVAILABLE_ACTION. Dieser wird nach Abschluss von Scananfragen aufgerufen und gibt den Status „Erfolg“ oder „Fehler“ an. Bei Geräten mit Android 10 (API-Level 29) und höher wird diese Nachricht für alle WLAN-Scans gesendet, die von der Plattform oder anderen Apps auf dem Gerät ausgeführt werden. Apps können alle Scanabschlüsse auf dem Gerät passiv überwachen, indem sie den Broadcast verwenden, ohne einen eigenen Scan auszugeben.
Fordern Sie einen Scan mit WifiManager.startScan() an. Prüfen Sie unbedingt den Rückgabestatus der Methode, da der Aufruf aus folgenden Gründen fehlschlagen kann:
- Scananfragen können aufgrund zu vieler Scans in kurzer Zeit gedrosselt werden.
- Das Gerät ist inaktiv und die Scanfunktion ist deaktiviert.
- Die WLAN-Hardware meldet einen Scanfehler.
Rufen Sie Scanergebnisse mit WifiManager.getScanResults() ab. Die zurückgegebenen Scanergebnisse sind die zuletzt aktualisierten Ergebnisse. Diese können aus einem vorherigen Scan stammen, wenn der aktuelle Scan nicht abgeschlossen oder erfolgreich war. Daher erhalten Sie möglicherweise ältere Scanergebnisse, wenn Sie diese Methode aufrufen, bevor Sie eine erfolgreiche SCAN_RESULTS_AVAILABLE_ACTION-Übertragung empfangen haben.

Der folgende Code enthält 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 WLAN-Scans eingeführt.

Um Netzwerkleistung, Sicherheit und Akkulaufzeit zu verbessern, wurden die Berechtigungsanforderungen von Android 9 (API-Level 28) 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 aufrufende App keine dieser Berechtigungen hat, schlägt der Aufruf mit einem SecurityException fehl.

Auf Geräten mit Android 8.0 (API-Level 26) und höher kannst du alternativ CompanionDeviceManager verwenden, um im Auftrag deiner App einen Scan von Companion-Geräten in der Nähe durchzufü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 Berechtigung ACCESS_FINE_LOCATION oder ACCESS_COARSE_LOCATION.
Ihre App hat die Berechtigung CHANGE_WIFI_STATE.
Die Standortdienste sind auf dem Gerät unter Einstellungen > Standort aktiviert.

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 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 unter Einstellungen > Standort aktiviert.

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 niedrigeres SDK als Android 10 (API-Level 29) ausgerichtet 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 unter Einstellungen > Standort aktiviert.

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 einen Scan in einem Zeitraum von 30 Minuten durchführen.

Android 9:

Jede App im Vordergrund kann viermal in einem Zeitraum von zwei Minuten einen Scan durchführen. Dies ermöglicht eine Reihe von Scans in kurzer Zeit.

Alle Hintergrund-Apps können in einem Zeitraum von 30 Minuten einmal gescannt werden.

Android 10 und höher:

Es gelten die gleichen Drosselungsbeschränkungen wie bei Android 9. Es gibt eine neue Option für Entwickler, mit der Sie die Drosselung für lokale Tests deaktivieren können (unter Entwickleroptionen > Netzwerk > Drosselung des WLAN-Scans).