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 .