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 sieci Wi-Fi), otrzymywanie z platformy informacji diagnostycznych o połączeniu z siecią. Te aplikacje mogą rejestrować wywołania zwrotne i otrzymywać powiadomienia z informacjami o połączeniu z sieciami, których są właścicielami lub którymi zarządzają. Aplikacje nie będą otrzymywać powiadomień o sieciach, których nie są właścicielami ani którymi nie zarządzają.

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

• Aplikacje operatorów: zarządzają sieciami komórkowymi, w których mają uprawnienia operatora w ramach subId.
• Aplikacje z sugestiami sieci Wi-Fi: są właścicielami sieci Wi-Fi, które sugerują systemowi.
• Aplikacje VPN: zarządzają wszystkimi sieciami, z których korzysta ich sieć 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 zablokowania danych: podejrzewane jest zablokowanie danych, czyli sytuacja, w której pakiety IP nie przepływają prawidłowo przez sieć. Klasa DataStallReport zawiera informacje o podejrzewanych zablokowaniach danych.

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

• Zgłoszenie połączenia: aplikacja zgłosiła systemowi połączenie za pomocą ConnectivityManager#reportNetworkConnectivity. Udostępniana jest sieć i zgłoszone połączenie (czy aplikacja uważa, że sieć zapewnia połączenie).

Implementacja

Aby korzystać z interfejsu Connectivity Diagnostics API, aplikacja musi uzyskać ConnectivityDiagnosticsManager instancję z platformy. Ta instancja powinna służyć do rejestrowania i wyrejestrowywania ConnectivityDiagnosticsCallback implementacji. Metody wywołania zwrotnego, które nie są zastępowane, 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, wywołaj registerConnectivityDiagnosticsCallback. Aby wyrejestrować wywołania zwrotne i przestać otrzymywać powiadomienia, wywołaj unregisterConnectivityDiagnosticsCallback.

Poniżej znajdziesz przykład rejestrowania i wyrejestrowywania 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 przez CTS za pomocą ConnectivityDiagnosticsManagerTest.