連接診斷 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 測試。