连接诊断 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向系统报告连接。共享网络和报告的连接(应用程序认为网络提供或不提供连接)是共享的。

执行

要使用 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);

验证

连接诊断 API 由ConnectivityDiagnosticsManagerTest进行 CTS 测试。