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 测试。