連線診斷 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);

驗證

連線診斷 API 已通過 ConnectivityDiagnosticsManagerTest 的 CTS 測試。