Interfejs Connectivity Diagnostics API

Interfejs Connectivity Diagnostics API umożliwia aplikacjom, które są właścicielami sieci lub nimi zarządzają, np. aplikacjom operatora, aplikacjom VPN i aplikacjom z sugestiami sieci Wi-Fi, otrzymywanie z ramy diagnostycznych informacji o połączeniu sieci. Te aplikacje mogą rejestrować wywołania zwrotne i otrzymywać powiadomienia z informacjami o połączeniach sieci, które są ich własnością lub którymi zarządzają. Aplikacje nie będą otrzymywać powiadomień z sieci, które nie należą do aplikacji ani nie są przez nią zarządzane.

Oto przykłady aplikacji, które zarządzają sieciami lub je obsługują:

• Aplikacje operatora:zarządzanie sieciami komórkowymi, w których przypadku subId ma uprawnienia operatora.
• aplikacje do sugerowania sieci Wi-Fi: własne sieci Wi-Fi, które sugerują systemowi;
• Aplikacje VPN: zarządzają wszystkimi sieciami, których używa VPN, ale tylko wtedy, gdy jest to aktywna sieć VPN.

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

• Weryfikacja sieci: system ukończył sprawdzanie określonej sieci. Klasa ConnectivityReport zawiera informacje o obecnym stanie sieci oraz wyniki wszelkich testów lub procedur przeprowadzonych w ramach walidacji.

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

• Podejrzenie o zatrzymanie danych: podejrzenie zatrzymania danych, czyli sytuacji, w której pakiety IP nie przepływają prawidłowo przez sieć. Klasa DataStallReport zawiera informacje o podejrzanych zastojach danych.

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

• Połączenie: aplikacja zgłosiła połączenie przez ConnectivityManager#reportNetworkConnectivity z systemem. Udostępnianie sieci i raportowanej łączności (czy aplikacja uważa, że sieć zapewnia łączność, czy nie).

Implementacja

Aby korzystać z interfejsu Connectivity Diagnostics API, aplikacja musi uzyskać instancję ConnectivityDiagnosticsManager od platformy. Ten obiekt powinien służyć do rejestrowania i odrejestrowywania implementacji ConnectivityDiagnosticsCallback. Metody wywołania zwrotnego, które nie są zastąpione, nie są wykonywane.

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 anulować rejestrację wywołań zwrotnych i zatrzymać otrzymywanie powiadomień, wywołaj funkcję unregisterConnectivityDiagnosticsCallback.

Oto 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 został przetestowany w ramach CTS przez ConnectivityDiagnosticsManagerTest.