Connectivity Diagnostics API

The Connectivity Diagnostics API allows apps that own or manage networks, such as carrier apps, VPN apps, and Wi-Fi suggestion apps, to receive diagnostic network connectivity information from the framework. These apps can register callbacks and receive notifications with connectivity information for the networks that they own or manage. Apps won't receive notifications for networks that aren't owned or managed by the app.

The following are examples of apps that manage or own networks:

• Carrier apps: Manage cellular networks for which their subId has carrier privileges for
• Wi-Fi suggestion apps: Own Wi-Fi networks that they suggest to the system
• VPN apps: Manage all networks that their VPN uses, but only when they are the active VPN

Callbacks are invoked in the following cases:

• Network validation: The system finished evaluating a specific network. The ConnectivityReport class provides information on the current state of the network and the results of any tests or procedures performed as part of the validation.

  public class ConnectivityReport {
      Network network;
      long reportTimestamp;
      LinkProperties linkProperties;
      NetworkCapabilities networkCapabilities;
      PersistableBundle additionalInfo;
  }
  

• Data stall suspected: A data stall, a condition in which IP packets aren't properly flowing through the network, is suspected. The DataStallReport class provides information about suspected data stalls.

  public class DataStallReport {
      Network network;
      long reportTimestamp;
      int detectionMethod;
      LinkProperties linkProperties;
      NetworkCapabilities networkCapabilities;
      PersistableBundle stallDetails;
  }
  

• Connectivity reported: An app has reported connectivity through ConnectivityManager#reportNetworkConnectivity to the system. The network and reported connectivity (whether the app believes the network does or doesn't provide connectivity) is shared.

Implementation

To use the Connectivity Diagnostics API, an app must obtain a ConnectivityDiagnosticsManager instance from the platform. This instance should be used to register and unregister ConnectivityDiagnosticsCallback implementations. Callback methods that aren't overridden are no-ops.

Below is an example of a ConnectivityDiagnosticsCallback implementation:

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
        ... 
    }
}

To register callbacks and receive notifications, call registerConnectivityDiagnosticsCallback. To unregister callbacks and stop receiving notifications, call unregisterConnectivityDiagnosticsCallback.

Below is an example for registering and unregistering 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);

Validation

The Connectivity Diagnostics API is CTS tested by ConnectivityDiagnosticsManagerTest.