Interfejs Connectivity Diagnostics API

Interfejs Connectivity Diagnostics API umożliwia aplikacjom, które są właścicielami sieci lub nimi zarządzają, np. aplikacjom operatorów, aplikacjom VPN i aplikacjom z sugestiami dotyczącymi Wi-Fi, otrzymywanie z frameworka informacji diagnostycznych o łączności sieciowej. Aplikacje te mogą rejestrować wywołania zwrotne i otrzymywać powiadomienia z informacjami o łączności w przypadku sieci, których są właścicielami lub którymi zarządzają. Aplikacje nie będą otrzymywać powiadomień o sieciach, które nie należą do nich ani nie są przez nie zarządzane.

Oto przykłady aplikacji, które zarządzają sieciami lub są ich właścicielami:

• Aplikacje operatora: zarządzanie sieciami komórkowymi, w przypadku których subIdma uprawnienia operatora.
• Aplikacje z sugestiami dotyczącymi Wi-Fi: własne sieci Wi-Fi, które sugerują systemowi.
• Aplikacje VPN: zarządzają wszystkimi sieciami, z których korzysta VPN, ale tylko wtedy, gdy są aktywną siecią VPN.

Wywołania zwrotne są wywoływane w tych przypadkach:

• Weryfikacja sieci: system zakończył ocenę konkretnej sieci. Klasa ConnectivityReport zawiera informacje o bieżącym stanie sieci oraz wyniki testów i procedur przeprowadzonych w ramach weryfikacji.

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

• Podejrzenie wstrzymania przesyłania danych: podejrzewamy wstrzymanie przesyłania danych, czyli stan, w którym pakiety IP nie są prawidłowo przesyłane przez sieć. Klasa DataStallReport zawiera informacje o podejrzewanych przestojach w przesyłaniu danych.

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

• Zgłoszono łączność: aplikacja zgłosiła łączność z systemem za pomocą ConnectivityManager#reportNetworkConnectivity Udostępniane są informacje o sieci i zgłoszonym połączeniu (czy aplikacja uważa, że sieć zapewnia połączenie).

Implementacja

Aby korzystać z interfejsu Connectivity Diagnostics API, aplikacja musi uzyskać instancję ConnectivityDiagnosticsManager z platformy. Ta instancja powinna być używana do rejestrowania i wyrejestrowywania implementacji ConnectivityDiagnosticsCallback. Metody wywołania zwrotnego, które nie zostały zastąpione, nie wykonują żadnych działań.

Poniżej znajdziesz przykład implementacji 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
        ... 
    }
}

Aby zarejestrować wywołania zwrotne i otrzymywać powiadomienia, zadzwoń pod numer registerConnectivityDiagnosticsCallback. Aby wyrejestrować wywołania zwrotne i przestać otrzymywać powiadomienia, wywołaj funkcję unregisterConnectivityDiagnosticsCallback.

Poniżej znajdziesz przykład rejestracji i wyrejestrowania: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);

Weryfikacja

Interfejs Connectivity Diagnostics API jest testowany w ramach CTS przez ConnectivityDiagnosticsManagerTest.