API диагностики подключения

API диагностики подключения позволяет приложениям, владеющим или управляющим сетями, например, приложениям операторов связи, VPN-приложениям и приложениям с рекомендациями по Wi-Fi, получать диагностическую информацию о сетевом подключении от фреймворка. Эти приложения могут регистрировать обратные вызовы и получать уведомления с информацией о подключении для сетей, которыми они владеют или управляют. Приложения не будут получать уведомления о сетях, которые не принадлежат или не управляются приложением.

Ниже приведены примеры приложений, которые управляют сетями или владеют ими:

  • Приложения оператора: управление сотовыми сетями, для которых их subId имеет привилегии оператора
  • Приложения для рекомендации сетей Wi-Fi: собственные сети Wi-Fi, которые они предлагают системе.
  • Приложения VPN: управляйте всеми сетями, которые использует их VPN, но только когда они являются активными VPN

Обратные вызовы вызываются в следующих случаях:

  • Проверка сети: система завершила оценку определённой сети. Класс ConnectivityReport предоставляет информацию о текущем состоянии сети и результатах всех тестов и процедур, выполненных в ходе проверки.

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

  • Подозрение на задержку данных: есть подозрение на задержку данных — состояние, при котором IP-пакеты не проходят через сеть должным образом. Класс DataStallReport предоставляет информацию о предполагаемых задержках данных.

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

  • Сообщения о подключении: приложение сообщило о подключении к системе через ConnectivityManager#reportNetworkConnectivity . Сеть и информация о подключении (считает ли приложение, что сеть обеспечивает подключение) являются общими.

Выполнение

Для использования API диагностики подключения приложение должно получить экземпляр ConnectivityDiagnosticsManager от платформы. Этот экземпляр следует использовать для регистрации и отмены регистрации реализаций ConnectivityDiagnosticsCallback . Непереопределенные методы обратного вызова не являются операциями.

Ниже приведен пример реализации 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
        ... 
    }
}

Чтобы зарегистрировать обратные вызовы и получать уведомления, вызовите registerConnectivityDiagnosticsCallback . Чтобы отменить регистрацию обратных вызовов и прекратить получение уведомлений, вызовите unregisterConnectivityDiagnosticsCallback .

Ниже приведен пример регистрации и отмены регистрации 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);

Проверка

API диагностики подключения протестировано CTS компанией ConnectivityDiagnosticsManagerTest .