Connectivity Diagnostics API

Mit der Connectivity Diagnostics API können Apps, die Netzwerke besitzen oder verwalten, z. B. Apps von Mobilfunkanbietern, VPN-Apps und WLAN-Vorschlags-Apps, diagnostische Informationen zur Netzwerkverbindung vom Framework erhalten. Diese Apps können Rückrufe registrieren und Benachrichtigungen mit Verbindungsinformationen für die Netzwerke empfangen, die ihnen gehören oder die sie verwalten. Apps erhalten keine Benachrichtigungen für Netzwerke, die nicht der App gehören oder von ihr verwaltet werden.

Hier einige Beispiele für Apps, die Netzwerke verwalten oder deren Inhaber sind:

• Apps von Mobilfunkanbietern:Mobilfunknetze verwalten, für die die subId über Anbieterberechtigungen verfügt
• Apps für WLAN-Vorschläge:Eigene WLANs, die sie dem System vorschlagen
• VPN-Apps:Sie verwalten alle Netzwerke, die von ihrem VPN verwendet werden, aber nur, wenn sie das aktive VPN sind.

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

• Netzwerkvalidierung:Das System hat die Auswertung eines bestimmten Netzwerks abgeschlossen. Die Klasse ConnectivityReport liefert 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;
  }
  

• Datenstau wird vermutet:Es wird ein Datenstau vermutet, bei dem IP-Pakete nicht richtig durch das Netzwerk fließen. Die Klasse DataStallReport enthält Informationen zu vermuteten Datenstaus.

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

• Gemeldete Konnektivität:Eine App hat dem System Konnektivität über ConnectivityManager#reportNetworkConnectivity gemeldet. Das Netzwerk und die gemeldete Verbindung (ob die App der Meinung ist, dass das Netzwerk eine Verbindung bereitstellt oder nicht) werden geteilt.

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 Deregistrieren von ConnectivityDiagnosticsCallback-Implementierungen verwendet werden. Callback-Methoden, die nicht überschrieben werden, sind managementfrei.

Unten sehen Sie ein Beispiel für die Implementierung von ConnectivityDiagnosticsCallback:

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

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

Unten sehen Sie ein Beispiel für die Registrierung und Deregistrierung von ConnectivityDiagnosticsCallback:

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);

Validierung

Die Connectivity Diagnostics API wird von ConnectivityDiagnosticsManagerTest im Rahmen des CTS getestet.