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 диагностики подключения протестирован в рамках проекта ConnectivityDiagnosticsManagerTest .