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