Connectivity Diagnostics API

Connectivity 診斷 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 的 CTS 已通過 ConnectivityDiagnosticsManagerTest。