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