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