Connectivity Diagnostics API

Mit der Connectivity Diagnostics API können Apps, die Netzwerke besitzen oder verwalten, z. B. Apps von Mobilfunkanbietern, VPN-Apps und Apps mit WLAN-Vorschlägen, Diagnoseinformationen zur Netzwerkverbindung vom Framework erhalten. Diese Apps können Rückrufe registrieren und Benachrichtigungen mit Informationen zur Konnektivität für die Netzwerke erhalten, deren Inhaber oder Administrator sie sind. Apps erhalten keine Benachrichtigungen für Netzwerke, die nicht der App gehören oder von ihr verwaltet werden.

Im Folgenden finden Sie Beispiele für Apps, die Netzwerke verwalten oder besitzen:

• Mobilfunkanbieter-Apps:Hier können Sie Mobilfunknetze verwalten, für die der subId-Nutzer Mobilfunkanbieterberechtigungen hat.
• Apps mit WLAN-Vorschlägen:Eigene WLANs, die dem System vorgeschlagen werden
• VPN-Apps:Verwalten aller Netzwerke, die von ihrem VPN verwendet werden, aber nur, wenn es sich um das aktive VPN handelt

In den folgenden Fällen werden Rückrufe aufgerufen:

• Netzwerküberprüfung:Die Bewertung eines bestimmten Netzwerks durch das System ist abgeschlossen. Die Klasse ConnectivityReport enthält Informationen zum aktuellen Status des Netzwerks und zu den Ergebnissen aller Tests oder Verfahren, die im Rahmen der Validierung durchgeführt wurden.

  public class ConnectivityReport {
      Network network;
      long reportTimestamp;
      LinkProperties linkProperties;
      NetworkCapabilities networkCapabilities;
      PersistableBundle additionalInfo;
  }
  

• Verdacht auf Datenstau:Es wird vermutet, dass es zu einem Datenstau kommt, bei dem IP-Pakete nicht richtig durch das Netzwerk geleitet werden. Die Klasse DataStallReport enthält Informationen zu vermuteten Datenstottern.

  public class DataStallReport {
      Network network;
      long reportTimestamp;
      int detectionMethod;
      LinkProperties linkProperties;
      NetworkCapabilities networkCapabilities;
      PersistableBundle stallDetails;
  }
  

• Verbindung gemeldet:Eine App hat eine Verbindung über ConnectivityManager#reportNetworkConnectivity zum System gemeldet. Das Netzwerk und die gemeldete Verbindung (ob die App der Meinung ist, dass das Netzwerk eine Verbindung herstellt oder nicht) werden weitergegeben.

Implementierung

Um die Connectivity Diagnostics API verwenden zu können, muss eine App eine ConnectivityDiagnosticsManager-Instanz von der Plattform abrufen. Diese Instanz sollte zum Registrieren und Entfernen von ConnectivityDiagnosticsCallback-Implementierungen verwendet werden. Callback-Methoden, die nicht überschrieben werden, werden nicht ausgeführt.

Unten sehen Sie ein Beispiel für eine ConnectivityDiagnosticsCallback-Implementierung:

public class ExampleCallback extends ConnectivityDiagnosticsCallback {
    @Override
    public void onConnectivityReportAvailable(@NonNull ConnectivityReport report) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }

    @Override
    public void onDataStallSuspected(@NonNull DataStallReport report) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }

    @Override
    public void onNetworkConnectivityReported(
               @NonNull Network network, boolean hasConnectivity) {
        ... 
        // Log data, take action based on report result, etc
        ... 
    }
}

Wenn Sie Rückrufe registrieren und Benachrichtigungen erhalten möchten, rufen Sie registerConnectivityDiagnosticsCallback auf. Wenn Sie keine Rückrufe mehr registrieren und keine Benachrichtigungen mehr erhalten möchten, rufen Sie unregisterConnectivityDiagnosticsCallback auf.

Im folgenden Beispiel wird ConnectivityDiagnosticsCallback registriert und wieder abgemeldet:

NetworkRequest request =
        new NetworkRequest.Builder()
                .addTransportType(TRANSPORT_CELLULAR)
                .build();
// Use an Executor that is appropriate for your use case
Executor executor = Executors.newSingleThreadExecutor();

ConnectivityDiagnosticsManager cdm =
        context.getSystemService(ConnectivityDiagnosticsManager.class);

ExampleCallback callback = new ExampleCallback();
cdm.registerConnectivityDiagnosticsCallback(
        request, executor, callback);

... 
// Collect connectivity information on networks that match with request
... 

cdm.unregisterConnectivityDiagnosticsCallback(callback);

Zertifizierungsstufe

Die Connectivity Diagnostics API wird von ConnectivityDiagnosticsManagerTest CTS-getestet.