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 .