Diese Seite wurde von der Cloud Translation API übersetzt.

Netzwerkstatus lesen

Mit Android können Apps sich über dynamische Veränderungen bei der Konnektivität informieren. Verwenden Sie die folgenden Klassen, um Konnektivitätsänderungen zu verfolgen und darauf zu reagieren:

ConnectivityManager informiert die App über den Verbindungsstatus im System.
Die Klasse Network stellt eines der Netzwerke dar, mit dem das Gerät verbunden ist. Sie können das Objekt Network als Schlüssel verwenden, um mit ConnectivityManager Informationen über das Netzwerk zu erhalten oder Sockets im Netzwerk zu binden. Wenn die Netzwerkverbindung getrennt wird, kann das Network-Objekt nicht mehr verwendet werden. Auch wenn das Gerät später wieder mit derselben Appliance verbunden wird, stellt ein neues Network-Objekt das neue Netzwerk dar.
Das Objekt LinkProperties enthält Informationen zur Verknüpfung für ein Netzwerk, z. B. die Liste der DNS-Server, lokalen IP-Adressen und Netzwerkrouten, die für das Netzwerk installiert sind.
Das Objekt NetworkCapabilities enthält Informationen zu den Attributen eines Netzwerks, z. B. die Übertragung (WLAN, Mobilfunk, Bluetooth) und die Fähigkeiten des Netzwerks. Sie können beispielsweise das Objekt abfragen, um festzustellen, ob das Netzwerk MMS senden kann, sich hinter einem Captive Portal befindet oder kostenpflichtig ist.

Anwendungen, die den unmittelbaren Zustand der Verbindung zu einem bestimmten Zeitpunkt ermitteln möchten, können ConnectivityManager-Methoden aufrufen, um herauszufinden, welche Art von Netzwerk verfügbar ist. Diese Methoden sind hilfreich beim Debugging und zum gelegentlichen Prüfen eines Snapshots der jederzeit verfügbaren Verbindung.

Da die synchronen ConnectivityManager-Methoden Ihre Anwendung jedoch nicht über Aktionen informieren, die nach einem Aufruf erfolgen, können Sie die UI nicht aktualisieren. Sie können das App-Verhalten auch nicht auf Grundlage der Netzwerktrennung oder Änderungen der Netzwerkfunktionen anpassen.

Die Konnektivität kann sich jederzeit ändern und die meisten Anwendungen müssen eine immer aktuelle, aktuelle Ansicht des Netzwerkstatus auf dem Gerät haben. Apps können einen Callback mit ConnectivityManager registrieren, um über Änderungen informiert zu werden, die für die App relevant sind. Mithilfe des Callbacks kann Ihre App sofort auf jede relevante Änderung der Konnektivität reagieren, ohne auf teure Abfragen zurückgreifen zu müssen, bei denen schnelle Aktualisierungen möglicherweise fehlen.

Die Verwendung von NetworkCallback und andere Methoden, um den Verbindungsstatus des Geräts zu ermitteln, erfordert keine bestimmte Berechtigung. Für einige Netzwerke gelten jedoch bestimmte Berechtigungen. So können beispielsweise eingeschränkte Netzwerke verfügbar sein, die für Anwendungen nicht verfügbar sind. Für die Bindung an ein Hintergrundnetzwerk ist die Berechtigung CHANGE_NETWORK_STATE erforderlich. Für einige Aufrufe sind möglicherweise bestimmte Berechtigungen erforderlich. Weitere Informationen finden Sie in der Dokumentation der einzelnen Aufrufe.

Aktuellen Status abrufen

Ein Android-Gerät kann viele Verbindungen gleichzeitig aufrechterhalten. Um Informationen zum aktuellen Netzwerkstatus zu erhalten, rufen Sie zuerst eine Instanz von ConnectivityManager ab:

Kotlin

val connectivityManager = getSystemService(ConnectivityManager::class.java)

Java

ConnectivityManager connectivityManager = getSystemService(ConnectivityManager.class);

Verwenden Sie diese Instanz als Nächstes, um für Ihre Anwendung einen Verweis auf das aktuelle Standardnetzwerk abzurufen:

Kotlin

val currentNetwork = connectivityManager.getActiveNetwork()

Java

Network currentNetwork = connectivityManager.getActiveNetwork();

Mit einem Verweis auf ein Netzwerk kann Ihre App Informationen dazu anfordern:

Kotlin

val caps = connectivityManager.getNetworkCapabilities(currentNetwork)
val linkProperties = connectivityManager.getLinkProperties(currentNetwork)

Java

NetworkCapabilities caps = connectivityManager.getNetworkCapabilities(currentNetwork);
LinkProperties linkProperties = connectivityManager.getLinkProperties(currentNetwork);

Registrieren Sie einen NetworkCallback, um nützlichere Funktionen zu erhalten. Weitere Informationen zum Registrieren von Netzwerk-Callbacks finden Sie unter Auf Netzwerkereignisse warten.

NetworkCapabilities und LinkProperties

Die Objekte NetworkCapabilities und LinkProperties liefern Informationen zu allen Attributen, die dem System über ein Netzwerk bekannt sind.

Das LinkProperties-Objekt kennt die Routen, Linkadressen, den Schnittstellennamen, Proxyinformationen (falls vorhanden) und die DNS-Server. Rufen Sie die entsprechende Methode für das LinkProperties-Objekt auf, um die benötigten Informationen abzurufen.

Das Objekt NetworkCapabilities enthält Informationen über das Netzwerk Transsports und die zugehörigen Funktionen.

Ein Transport ist eine Abstraktion eines physischen Mediums, über das ein Netzwerk betrieben wird. Gängige Beispiele für Übertragungen sind Ethernet, WLAN und Mobilgeräte. VPNs und Peer-to-Peer-WLAN können ebenfalls übertragen werden. Unter Android kann ein Netzwerk mehrere Transporte gleichzeitig haben. Ein Beispiel hierfür ist ein VPN, das sowohl über WLAN als auch über Mobilfunknetze betrieben wird. Das VPN dient für die WLAN-, Mobilfunk- und VPN-Transporte. Um herauszufinden, ob ein Netzwerk einen bestimmten Transport hat, verwenden Sie die Methode NetworkCapabilities.hasTransport(int) mit einer der NetworkCapabilities.TRANSPORT_*-Konstanten.

Eine Capability beschreibt eine Eigenschaft des Netzwerks. Beispiele für Funktionen sind MMS, NOT_METERED und INTERNET. Ein Netzwerk mit MMS-Funktion kann Nachrichten des Multimedia Messaging Service senden und empfangen, ein Netzwerk ohne diese Funktion nicht. In einem Netzwerk mit der Funktion NOT_METERED werden dem Nutzer keine Daten in Rechnung gestellt. Ihre Anwendung kann mithilfe der Methode NetworkCapabilities.hasCapability(int) und einer der NetworkCapabilities.NET_CAPABILITY_*-Konstanten prüfen, ob geeignete Funktionen vorhanden sind.

Zu den nützlichsten NET_CAPABILITY_*-Konstanten gehören:

NET_CAPABILITY_INTERNET: Gibt an, dass das Netzwerk für den Zugriff auf das Internet eingerichtet ist. Es geht um die Einrichtung und nicht um die Möglichkeit, öffentliche Server zu erreichen. Ein Netzwerk kann beispielsweise so eingerichtet sein, dass es auf das Internet zugreift, aber einem Captive Portal unterliegt.

Das Mobilfunknetz eines Mobilfunkanbieters hat in der Regel die Funktion INTERNET, lokale P2P-WLANs normalerweise nicht. Informationen zur Verbindung finden Sie unter NET_CAPABILITY_VALIDATED.
NET_CAPABILITY_NOT_METERED: Gibt an, dass das Netzwerk nicht kostenpflichtig ist. Ein Netzwerk gilt als kostenpflichtig, wenn der Nutzer aufgrund von finanziellen Kosten, Dateneinschränkungen oder Problemen mit der Akkuleistung empfindlich auf eine hohe Datennutzung bei dieser Verbindung reagiert.
NET_CAPABILITY_NOT_VPN: Gibt an, dass das Netzwerk kein virtuelles privates Netzwerk ist.
NET_CAPABILITY_VALIDATED: Gibt an, dass das Netzwerk bei einer Prüfung tatsächlichen Zugriff auf das öffentliche Internet bietet. Ein Netzwerk hinter einem Captive Portal oder ein Netzwerk, das keine Auflösung des Domainnamens bietet, hat diese Funktion nicht. Dies ist die genaueste Information, die das System von einem Netzwerk ableiten kann, das tatsächlich Zugriff bietet. Allerdings kann ein validiertes Netzwerk dennoch IP-basierten Filtern unterliegen oder aufgrund von Problemen wie einem schlechten Empfang plötzliche Verbindungsverluste erleiden.
NET_CAPABILITY_CAPTIVE_PORTAL: Gibt an, dass das Netzwerk ein Captive Portal hat, wenn es geprüft wird.

Spezialisierte Anwendungen könnten aber auch für andere Funktionen interessant sein. Weitere Informationen finden Sie in den Parameterdefinitionen in NetworkCapabilities.hasCapability(int).

Die Funktionen eines Netzwerks können sich jederzeit ändern. Wenn das System ein Captive Portal erkennt, zeigt es eine Benachrichtigung an, die den Nutzer zur Anmeldung auffordert. Währenddessen hat das Netzwerk die Funktionen NET_CAPABILITY_INTERNET und NET_CAPABILITY_CAPTIVE_PORTAL, aber nicht die Funktionen NET_CAPABILITY_VALIDATED.

Wenn der Nutzer eine Aktion ausführt und sich auf der Captive-Portal-Seite anmeldet, kann das Gerät auf das öffentliche Internet zugreifen und das Netzwerk erhält die Funktion NET_CAPABILITY_VALIDATED und verliert die Berechtigung NET_CAPABILITY_CAPTIVE_PORTAL.

Ebenso können sich die Transporte eines Netzwerks dynamisch ändern. Beispielsweise kann ein VPN sich neu konfigurieren, um ein schnelleres Netzwerk zu verwenden, z. B. den Wechsel von einem Mobilfunknetz zum WLAN für das zugrunde liegende Netzwerk. In diesem Fall verliert das Netzwerk den TRANSPORT_CELLULAR-Transport und erhält den TRANSPORT_WIFI-Transport, während das TRANSPORT_VPN-Transport beibehalten wird.

Netzwerkereignisse überwachen

Verwenden Sie die Klasse NetworkCallback zusammen mit ConnectivityManager.registerDefaultNetworkCallback(NetworkCallback) und ConnectivityManager.registerNetworkCallback(NetworkCallback), um mehr über Netzwerkereignisse zu erfahren. Diese beiden Methoden dienen unterschiedlichen Zwecken.

Alle Android-Apps haben ein Standardnetzwerk, das vom System festgelegt wird. Das System bevorzugt in der Regel kostenlose Netzwerke gegenüber kostenpflichtigen und schnellere den langsameren.

Wenn eine Anwendung eine Netzwerkanfrage sendet, z. B. über HttpsURLConnection, erfüllt das System diese Anfrage über das Standardnetzwerk. Apps können auch Traffic über andere Netzwerke senden. Weitere Informationen finden Sie im Abschnitt über zusätzliche Netzwerke.

Das Netzwerk, das als Standardnetzwerk festgelegt ist, kann sich während der Lebensdauer einer App jederzeit ändern. Ein typisches Beispiel ist ein Gerät, das sich in Reichweite eines bekannten, aktiven, kostenlosen und schnelleren WLAN-Zugangspunkts befindet. Das Gerät stellt eine Verbindung zu diesem Zugangspunkt her und schaltet das Standardnetzwerk für alle Apps auf das neue WLAN um.

Wenn ein neues Netzwerk als Standard festgelegt wird, verwendet jede neue Verbindung, die von der App geöffnet wird, dieses Netzwerk. Zu einem späteren Zeitpunkt wird die Beendigung aller verbleibenden Verbindungen im vorherigen Standardnetzwerk erzwungen. Wenn die Anwendung wissen muss, wann sich das Standardnetzwerk ändert, wird so ein Standardnetzwerk-Callback registriert:

Kotlin

connectivityManager.registerDefaultNetworkCallback(object : ConnectivityManager.NetworkCallback() {
    override fun onAvailable(network : Network) {
        Log.e(TAG, "The default network is now: " + network)
    }

    override fun onLost(network : Network) {
        Log.e(TAG, "The application no longer has a default network. The last default network was " + network)
    }

    override fun onCapabilitiesChanged(network : Network, networkCapabilities : NetworkCapabilities) {
        Log.e(TAG, "The default network changed capabilities: " + networkCapabilities)
    }

    override fun onLinkPropertiesChanged(network : Network, linkProperties : LinkProperties) {
        Log.e(TAG, "The default network changed link properties: " + linkProperties)
    }
})

Java

connectivityManager.registerDefaultNetworkCallback(new ConnectivityManager.NetworkCallback() {
    @Override
    public void onAvailable(Network network) {
        Log.e(TAG, "The default network is now: " + network);
    }

    @Override
    public void onLost(Network network) {
        Log.e(TAG, "The application no longer has a default network. The last default network was " + network);
    }

    @Override
    public void onCapabilitiesChanged(Network network, NetworkCapabilities networkCapabilities) {
        Log.e(TAG, "The default network changed capabilities: " + networkCapabilities);
    }

    @Override
    public void onLinkPropertiesChanged(Network network, LinkProperties linkProperties) {
        Log.e(TAG, "The default network changed link properties: " + linkProperties);
    }
});

Wenn ein neues Netzwerk zum Standard wird, erhält die App einen Aufruf an onAvailable(Network) für das neue Netzwerk. Implementieren Sie onCapabilitiesChanged(Network,NetworkCapabilities), onLinkPropertiesChanged(Network,LinkProperties) oder beide, um angemessen auf Änderungen der Konnektivität zu reagieren.

Bei einem Callback, der mit registerDefaultNetworkCallback() registriert ist, bedeutet onLost(), dass das Netzwerk nicht mehr das Standardnetzwerk ist. Möglicherweise ist die Verbindung getrennt.

Wenn Sie NetworkCapabilities.hasTransport(int) abfragen, können Sie zwar etwas über die Transportvorgänge erfahren, die das Standardnetzwerk verwendet, aber dies ist ein schlechter Proxy für die Bandbreite oder die Messwerte des Netzwerks. Ihre App kann nicht davon ausgehen, dass WLAN immer gebührenfrei ist und immer eine bessere Bandbreite als ein Mobilfunknetz bietet.

Verwenden Sie stattdessen NetworkCapabilities.getLinkDownstreamBandwidthKbps() zum Messen der Bandbreite und NetworkCapabilites.hasCapability(int) mit NET_CAPABILITY_NOT_METERED-Argumenten, um die Begrenzung zu bestimmen. Weitere Informationen finden Sie im Abschnitt über NetworkCapabilities und LinkProperties.

Standardmäßig werden die Callback-Methoden für den Konnektivitätsthread der Anwendung aufgerufen. Das ist ein separater Thread, der von ConnectivityManager verwendet wird. Wenn Ihre Implementierung der Callbacks nicht mehr funktioniert, können Sie sie mit der Variante ConnectivityManager.registerDefaultNetworkCallback(NetworkCallback, Handler) in einem separaten Worker-Thread aufrufen.

Die Registrierung eines Callbacks kann durch Aufrufen von ConnectivityManager.unregisterNetworkCallback(NetworkCallback) aufgehoben werden, wenn Sie ihn nicht mehr verwenden. Das onPause() deiner Hauptaktivität eignet sich gut dafür, insbesondere wenn du den Callback in onResume() registrierst.

Zusätzliche Netzwerke

Obwohl das Standardnetzwerk für die meisten Anwendungen das einzige relevante Netzwerk ist, sind einige Anwendungen möglicherweise an anderen verfügbaren Netzwerken interessiert. Um mehr darüber zu erfahren, erstellen Apps einen NetworkRequest, der ihren Anforderungen entspricht, und rufen ConnectivityManager.registerNetworkCallback(NetworkRequest, NetworkCallback) auf.

Der Vorgang ähnelt dem Überwachen eines Standardnetzwerks. Obwohl es möglicherweise immer nur ein Standardnetzwerk für eine App gibt, kann Ihre App mit dieser Version alle verfügbaren Netzwerke gleichzeitig sehen. Ein Aufruf von onLost(Network) bedeutet also, dass das Netzwerk dauerhaft getrennt wurde und nicht mehr das Standardnetzwerk ist.

Die App erstellt eine NetworkRequest, um ConnectivityManager darüber zu informieren, welche Art von Netzwerken sie überwachen möchte. Das folgende Beispiel zeigt, wie Sie eine NetworkRequest für eine Anwendung erstellen, die nur an kostenlosen Internetverbindungen interessiert ist:

Kotlin

val request = NetworkRequest.Builder()
  .addCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
  .addCapability(NET_CAPABILITY_INTERNET)
  .build()

connectivityManager.registerNetworkCallback(request, myNetworkCallback)

Java

NetworkRequest request = new NetworkRequest.Builder()
  .addCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED)
  .addCapability(NET_CAPABILITY_INTERNET)
  .build();

connectivityManager.registerNetworkCallback(request, myNetworkCallback);

Das bedeutet, dass Ihre Anwendung von allen Änderungen in Bezug auf kostenlose Netzwerke im System erfährt.

Für den Standardnetzwerk-Callback gibt es eine Version von registerNetworkCallback(NetworkRequest, NetworkCallback, Handler), die einen Handler akzeptiert, damit der Connectivity-Thread der Anwendung nicht geladen wird.

Rufen Sie ConnectivityManager.unregisterNetworkCallback(NetworkCallback) auf, wenn der Callback nicht mehr relevant ist. Eine App kann mehrere Netzwerk-Callbacks gleichzeitig registrieren.

Der Einfachheit halber enthält das Objekt NetworkRequest die gängigen Funktionen, die die meisten Anwendungen benötigen, darunter:

Prüfen Sie beim Schreiben Ihrer Anwendung die Standardeinstellungen, um festzustellen, ob sie Ihrem Anwendungsfall entsprechen. Löschen Sie sie, wenn Ihre Anwendung über Netzwerke benachrichtigt werden soll, die diese Funktionen nicht haben. Fügen Sie andererseits Funktionen hinzu, um zu vermeiden, dass Sie bei Verbindungsänderungen in Netzwerken aufgerufen werden, mit denen Ihre Anwendung nicht interagiert.

Wenn Ihre Anwendung beispielsweise MMS senden muss, fügen Sie NET_CAPABILITY_MMS zu NetworkRequest hinzu, damit Sie nicht über alle Netzwerke informiert werden, die keine MMS senden können. Fügen Sie TRANSPORT_WIFI_AWARE hinzu, wenn Ihre App nur an P2P-WLAN-Verbindungen interessiert ist. NET_CAPABILITY_INTERNET und NET_CAPABILITY_VALIDATED sind hilfreich, wenn Sie Daten mit einem Server im Internet übertragen möchten.

Beispiel für Callback-Sequenz

In diesem Abschnitt wird die Abfolge von Callbacks beschrieben, die eine App erhalten kann, wenn sie auf einem Gerät mit Mobilfunkverbindung sowohl einen Standard- als auch einen normalen Callback registriert. In diesem Beispiel stellt das Gerät eine Verbindung zu einem guten WLAN-Zugangspunkt her und trennt dann die Verbindung zu diesem. In diesem Beispiel wird außerdem davon ausgegangen, dass auf dem Gerät die Einstellung Mobile Daten immer aktiviert aktiviert ist.

Der Zeitplan sieht so aus:

Wenn die App registerNetworkCallback() aufruft, empfängt der Callback sofort Anrufe von onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged() für das Mobilfunknetz, da nur dieses Netzwerk verfügbar ist. Wenn ein anderes Netzwerk verfügbar ist, empfängt die App auch Callbacks für das andere Netzwerk.

Abbildung 1: App-Status nach dem Aufruf von registerNetworkCallback().
Anschließend ruft die App registerDefaultNetworkCallback() auf. Der Standardnetzwerk-Callback empfängt Aufrufe an onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged() für das Mobilfunknetz, da das Mobilfunknetz das Standardnetzwerk ist. Wenn ein anderes nicht standardmäßiges Netzwerk aktiv ist, kann die App keine Aufrufe für dieses nicht standardmäßige Netzwerk empfangen.

Abbildung 2: App-Status nach der Registrierung eines Standardnetzwerks
Später stellt das Gerät eine Verbindung zu einem (kostenlosen) WLAN her. Der reguläre Netzwerk-Callback empfängt Aufrufe an onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged() für das WLAN.

Abbildung 3: App-Status nach dem Herstellen einer Verbindung zu einem kostenlosen WLAN.
An dieser Stelle kann es eine Weile dauern, bis das WLAN validiert ist. In diesem Fall enthalten die onNetworkCapabilitiesChanged()-Aufrufe für den regulären Netzwerk-Callback keine Funktion NET_CAPABILITY_VALIDATED. Nach kurzer Zeit erhält sie einen Aufruf von onNetworkCapabilitiesChanged(), wobei die neuen Funktionen NET_CAPABILITY_VALIDATED enthalten. In den meisten Fällen geht die Validierung sehr schnell.

Wenn das WLAN validiert wird, bevorzugt das System es dem Mobilfunknetz, hauptsächlich, weil es kostenlos ist. Das WLAN wird zum Standardnetzwerk, sodass der Standardnetzwerk-Callback einen Aufruf an onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged() für das WLAN empfängt. Das Mobilfunknetz geht in den Hintergrund und der reguläre Netzwerk-Callback empfängt einen Aufruf an onLosing() für das Mobilfunknetz.

Da in diesem Beispiel davon ausgegangen wird, dass mobile Daten für dieses Gerät immer aktiviert sind, wird die Verbindung zum Mobilfunknetz nie getrennt. Wenn die Einstellung deaktiviert ist, wird die Verbindung zum Mobilfunknetz nach einer Weile getrennt und der reguläre Netzwerk-Callback empfängt einen Aufruf an onLost().

Abbildung 4: App-Status nach der WLAN-Validierung
Später wird das Gerät plötzlich vom WLAN getrennt, da es außer Reichweite war. Da die WLAN-Verbindung getrennt wird, erhält der reguläre Netzwerk-Callback einen WLAN-Aufruf an onLost(). Da das Mobilfunknetz das neue Standardnetzwerk ist, empfängt der Standardnetzwerk-Callback Aufrufe an onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged() für das Mobilfunknetz.

Abbildung 5: App-Status nach dem Trennen der Verbindung zum WLAN

Wenn die Einstellung Mobile Daten immer aktiviert deaktiviert ist, wird beim Trennen der WLAN-Verbindung versucht, das Gerät wieder mit einem Mobilfunknetz zu verbinden. Das Bild ist ähnlich, aber mit einer kurzen zusätzlichen Verzögerung für die onAvailable()-Aufrufe. Der reguläre Netzwerk-Callback empfängt auch Aufrufe an onAvailable(), onNetworkCapabilitiesChanged() und onLinkPropertiesChanged(), da Mobilgeräte verfügbar werden.

Einschränkungen für die Verwendung des Netzwerks für die Datenübertragung

Ein Netzwerk mit einem Netzwerk-Callback zu sehen bedeutet nicht, dass Ihre App das Netzwerk für die Datenübertragung verwenden kann. Einige Netzwerke bieten keine Internetverbindung und andere sind möglicherweise auf privilegierte Anwendungen beschränkt. Informationen zum Prüfen der Internetverbindung finden Sie unter NET_CAPABILITY_INTERNET und NET_CAPABILITY_VALIDATED.

Die Verwendung von Hintergrundnetzwerken unterliegt ebenfalls Berechtigungsprüfungen. Wenn Ihre App ein Hintergrundnetzwerk verwenden möchte, benötigt sie die Berechtigung CHANGE_NETWORK_STATE.

Apps mit dieser Berechtigung ermöglichen es dem System, ein Netzwerk aufzurufen, das nicht erreichbar ist, z. B. das Mobilfunknetz, wenn das Gerät mit einem WLAN-Netzwerk verbunden ist. Eine solche App ruft ConnectivityManager.requestNetwork(NetworkRequest, NetworkCallback) mit einem NetworkCallback auf, das aufgerufen wird, wenn das Netzwerk bereitgestellt wird.