連接診斷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與系統的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已通過ConnectivityDiagnosticsManagerTest進行了CTS測試。