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