Connectivity Diagnostics API

如果應用程式擁有或管理網路 (例如電信業者應用程式、VPN 應用程式和 Wi-Fi 建議應用程式)，就能透過連線診斷 API 從架構接收診斷網路連線資訊。這些應用程式可以註冊回呼，並接收所擁有或管理的網路連線資訊通知。應用程式不會收到不屬於或不歸應用程式管理的聯播網通知。

以下是管理或擁有網路的應用程式範例：

  • 電信業者應用程式：管理具有電信業者特殊權限的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 向系統回報連線狀態。系統會分享網路和回報的連線狀態 (應用程式是否認為網路提供連線)。

實作

如要使用連線診斷 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 會由 CTS 測試 ConnectivityDiagnosticsManagerTest。