Connectivity Diagnostics 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. Сеть и информация о подключении (есть ли оно, по мнению приложения) передаются.

Реализация

Чтобы использовать Connectivity Diagnostics 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);

Проверка

Connectivity Diagnostics API тестируется CTS с помощью ConnectivityDiagnosticsManagerTest.