Connectivity Diagnostics 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);

検証

Connectivity Diagnostics API の CTS テストは、ConnectivityDiagnosticsManagerTest で行います。