Connectivity Diagnostics API

Connectivity Diagnostics 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 已由 ConnectivityDiagnosticsManagerTest 进行 CTS 测试。