API Connectivity Diagnostics

A API Connectivity Diagnostics permite que apps que têm ou gerenciam redes, como apps de operadora, VPN e sugestão de Wi-Fi, recebam informações de diagnóstico de conectividade de rede do framework. Esses apps podem registrar callbacks e receber notificações com informações de conectividade das redes que eles possuem ou gerenciam. Os apps não recebem notificações de redes que não são de propriedade ou gerenciadas pelo app.

Confira abaixo exemplos de apps que gerenciam ou possuem redes:

• Apps da operadora:gerenciar redes celulares para as quais o subId tem privilégios de operadora.
• Apps de sugestão de Wi-Fi:têm redes Wi-Fi próprias que sugerem ao sistema.
• Apps de VPN:gerenciam todas as redes que a VPN usa, mas apenas quando ela é a VPN ativa.

Os callbacks são invocados nos seguintes casos:

• Validação de rede:o sistema terminou de avaliar uma rede específica. A classe ConnectivityReport fornece informações sobre o estado atual da rede e os resultados de todos os testes ou procedimentos realizados como parte da validação.

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

• Suspeição de interrupção de dados:há suspeita de interrupção de dados, uma condição em que os pacotes IP não fluem corretamente pela rede. A classe DataStallReport fornece informações sobre suspeitas de interrupções de dados.

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

• Conectividade informada:um app informou a conectividade pelo ConnectivityManager#reportNetworkConnectivity ao sistema. A rede e a conectividade informada (se o app acredita que a rede fornece ou não conectividade) são compartilhadas.

Implementação

Para usar a API Connectivity Diagnostics, um app precisa receber uma instância ConnectivityDiagnosticsManager da plataforma. Essa instância precisa ser usada para registrar e cancelar o registro de implementações do ConnectivityDiagnosticsCallback. Os métodos de callback que não são substituídos são operações nulas.

Confira abaixo um exemplo de implementação de 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 callbacks e receber notificações, chame registerConnectivityDiagnosticsCallback. Para cancelar o registro de callbacks e parar de receber notificações, chame unregisterConnectivityDiagnosticsCallback.

Confira abaixo um exemplo de registro e cancelamento de 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);

Validação

A API Connectivity Diagnostics é testada pelo CTS por ConnectivityDiagnosticsManagerTest.