API de diagnóstico de conectividad

La API de diagnóstico de conectividad permite que las aplicaciones que poseen o administran redes, como aplicaciones de operadores, aplicaciones VPN y aplicaciones de sugerencias de Wi-Fi, reciban información de diagnóstico de conectividad de red desde el marco. Estas aplicaciones pueden registrar devoluciones de llamadas y recibir notificaciones con información de conectividad para las redes que poseen o administran. Las aplicaciones no recibirán notificaciones de redes que no sean propiedad de la aplicación ni estén administradas por ella.

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

• Aplicaciones de operador: administre redes celulares para las cuales su subId tiene privilegios de operador.
• Apps de sugerencia de Wi-Fi: Redes Wi-Fi propias que sugieren al sistema
• Aplicaciones VPN: administre todas las redes que utiliza su VPN, pero solo cuando sean 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 ConnectivityReport 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.

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

• Sospecha de bloqueo de datos: se sospecha un bloqueo 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 sospechas de bloqueos de datos.

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

• Conectividad informada: una aplicación ha informado de conectividad a través de ConnectivityManager#reportNetworkConnectivity al sistema. La red y la conectividad informada (si la aplicación cree que la red proporciona o no conectividad) se comparten.

Implementación

Nota: Las aplicaciones que registran devoluciones de llamadas deben tener el permiso ACCESS_FINE_LOCATION porque conectarse a redes de ubicaciones específicas puede exponer la ubicación precisa del usuario.

Para utilizar la API de Connectivity Diagnostics, una aplicación debe obtener una instancia ConnectivityDiagnosticsManager de la plataforma. Esta instancia debe usarse para registrar y cancelar el registro de implementaciones ConnectivityDiagnosticsCallback . Los métodos de devolución de llamada que no se anulan no son operativos.

A continuación se muestra un ejemplo de una implementación 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
        ... 
    }
}

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

Nota: Las devoluciones de llamada deben registrarse y cancelarse utilizando el mismo uid .

A continuación se muestra un ejemplo para registrar y cancelar el registro 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 está probada por CTS mediante ConnectivityDiagnosticsManagerTest .