Interfejs API diagnostyki łączności

Interfejs API Connectivity Diagnostics umożliwia aplikacjom będącym właścicielami sieci lub zarządzającymi sieciami, takim jak aplikacje operatora, aplikacje VPN i aplikacje z sugestiami Wi-Fi, otrzymywanie informacji diagnostycznych o łączności sieciowej z platformy. Te aplikacje mogą rejestrować wywołania zwrotne i otrzymywać powiadomienia z informacjami o łączności w sieciach, których są właścicielami lub którymi zarządzają. Aplikacje nie będą otrzymywać powiadomień w przypadku sieci, które nie są ich własnością ani nie są zarządzane przez aplikację.

Poniżej znajdują się przykłady aplikacji, które zarządzają sieciami lub są ich właścicielami:

  • Aplikacje operatora: zarządzaj sieciami komórkowymi, do których subId ma uprawnienia operatora
  • Aplikacje z sugestiami Wi-Fi: własne sieci Wi-Fi, które sugerują systemowi
  • Aplikacje VPN: zarządzaj wszystkimi sieciami, z których korzysta ich VPN, ale tylko wtedy, gdy są one aktywną siecią VPN

Wywołania zwrotne wywoływane są w następujących przypadkach:

  • Walidacja sieci: system zakończył ocenę określonej sieci. Klasa ConnectivityReport dostarcza informacji o aktualnym stanie sieci oraz wynikach wszelkich testów czy procedur wykonanych w ramach walidacji.

    public class ConnectivityReport {
        Network network;
        long reportTimestamp;
        LinkProperties linkProperties;
        NetworkCapabilities networkCapabilities;
        PersistableBundle additionalInfo;
    }
    
  • Podejrzewa się zatrzymanie danych: Podejrzewa się zatrzymanie danych, czyli stan, w którym pakiety IP nie przepływają prawidłowo przez sieć. Klasa DataStallReport dostarcza informacji o podejrzanych przestojach 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 pośrednictwem ConnectivityManager#reportNetworkConnectivity . Sieć i zgłoszona łączność (niezależnie od tego, czy aplikacja uważa, że ​​sieć zapewnia łączność, czy nie) są udostępniane.

Realizacja

Aby móc korzystać z interfejsu API Connectivity Diagnostics, aplikacja musi uzyskać instancję ConnectivityDiagnosticsManager z platformy. To wystąpienie powinno służyć do rejestrowania i wyrejestrowywania implementacji ConnectivityDiagnosticsCallback . Metody wywołania zwrotnego, które nie zostaną zastąpione, nie działają.

Poniżej znajduje się 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, zadzwoń pod numer unregisterConnectivityDiagnosticsCallback .

Poniżej znajduje się 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);

Walidacja

Interfejs API diagnostyki łączności jest testowany przez CTS za pomocą ConnectivityDiagnosticsManagerTest .