API de diagnóstico de conectividad

La API de diagnóstico de conectividad permite que las apps que tienen o administran redes, como las de proveedores, de VPN y de sugerencias de Wi-Fi, reciban información de diagnóstico de conectividad de red del framework. Estas apps pueden registrar devoluciones de llamada y recibir notificaciones con información de conectividad para las redes que poseen o administran. Las apps no recibirán notificaciones de redes que no sean de su propiedad o que no administren.

Los siguientes son ejemplos de apps que administran o poseen redes:

• Apps de proveedores: Administran redes celulares para las que su subId tiene privilegios de proveedor.
• Apps de sugerencias de Wi-Fi: Poseen redes Wi-Fi que sugieren al sistema.
• Apps de VPN: Administran todas las redes que usa su VPN, pero solo cuando son la VPN activa.

Las devoluciones de llamada se invocan en los siguientes casos:

• Validación de red: El sistema terminó de evaluar una red específica. La clase proporciona información sobre el estado actual de la red y los resultados de cualquier prueba o procedimiento realizado como parte de la validación.ConnectivityReport

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

• Se sospecha de una detención de datos: Se sospecha de una detención de datos, una condición en la que los paquetes IP no fluyen correctamente a través de la red. La clase DataStallReport proporciona información sobre las detenciones de datos sospechosas.

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

• Se informó la conectividad: Una app informó la conectividad a través de ConnectivityManager#reportNetworkConnectivity al sistema. Se comparte la red y la conectividad informada (si la app cree que la red proporciona o no conectividad).

Implementación

Para usar la API de diagnóstico de conectividad, una app debe obtener una ConnectivityDiagnosticsManager instancia de la plataforma. Esta instancia se debe usar para registrar y cancelar el registro de las ConnectivityDiagnosticsCallback implementaciones. Los métodos de devolución de llamada que no se anulan son no-ops.

A continuación, se muestra un ejemplo de una ConnectivityDiagnosticsCallback implementación:

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

Para registrar devoluciones de llamada y recibir notificaciones, llama a registerConnectivityDiagnosticsCallback. Para cancelar el registro de devoluciones de llamada y dejar de recibir notificaciones, llama a unregisterConnectivityDiagnosticsCallback.

A continuación, se muestra un ejemplo para registrar y cancelar el registro de 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);

Validación

La API de diagnóstico de conectividad se prueba con CTS mediante ConnectivityDiagnosticsManagerTest.