Interfejs Connectivity Diagnostic API

Interfejs Connectivity Diagnostics API umożliwia aplikacjom, które są właścicielami sieci lub nimi zarządzają, takim jak aplikacje operatora, aplikacje VPN i aplikacje z sugestiami dotyczącymi Wi-Fi, otrzymywanie z ramy diagnostycznych informacji o połączeniu sieci. Aplikacje te mogą rejestrować wywołania zwrotne i otrzymywać powiadomienia z informacjami o połączeniach z sieciami, 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 używanymi przez VPN, ale tylko wtedy, gdy są aktywne.

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

• 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 przerwy na dane: istnieje podejrzenie zatrzymania danych, czyli warunku, w którym 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;
  }
  

• Zgłoszenie dotyczące łączności: aplikacja zgłosiła łączność przez ConnectivityManager#reportNetworkConnectivityz systemem. Udostępnianie sieci i raportowanej łączności (czy aplikacja uważa, że sieć zapewnia łączność, czy nie).

Implementacja

Aby korzystać z Connectivity Diagnostics API, aplikacja musi uzyskać instancję ConnectivityDiagnosticsManager od platformy. Tej instancji należy używać do rejestrowania i wyrejestrowania implementacji ConnectivityDiagnosticsCallback. Metody wywołania zwrotnego, które nie zostały zastąpione, nie są zastępowane.

Oto 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 jest testowany przez usługę ConnectivityDiagnosticsManagerTest.