Konnektivitätsdiagnose-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 die subId des Kunden Mobilfunkanbieterberechtigungen hat.
• Apps für WLAN-Vorschläge:Sie besitzen die eigenen WLAN-Netzwerke, die dem System vorgeschlagen werden.
• VPN-Apps:Verwalten aller Netzwerke, die von ihrem VPN verwendet werden, aber nur, wenn es das aktive VPN ist

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

• Verdachte Datenverzögerung: Es besteht der Verdacht, dass IP-Pakete nicht ordnungsgemäß durch das Netzwerk fließen. 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

Hinweis :Apps, die Callbacks registrieren, müssen die Berechtigung ACCESS_FINE_LOCATION haben, da durch die Verbindung mit standortspezifischen Netzwerken der genaue Standort des Nutzers offengelegt werden kann.

Um die Connectivity Diagnostics API zu verwenden, 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
        ... 
    }
}

Rufen Sie registerConnectivityDiagnosticsCallback auf, um Callbacks zu registrieren und Benachrichtigungen zu erhalten. Wenn Sie die Registrierung von Callbacks aufheben und keine Benachrichtigungen mehr erhalten möchten, rufen Sie unregisterConnectivityDiagnosticsCallback auf.

Hinweis: Die Callbacks müssen mit derselben uid registriert und wieder abgemeldet werden.

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.