API Connectivity Diagnostics

L'API Diagnostica della connettività consente alle app che possiedono o gestiscono reti, come le app degli operatori, le app VPN e le app di suggerimenti per il Wi-Fi, di ricevere informazioni diagnostiche sulla connettività di rete dal framework. Queste app possono registrare i callback e ricevere notifiche con informazioni sulla connettività per le reti di cui sono proprietarie o che gestiscono. Le app non riceveranno notifiche per le reti di cui non sono proprietarie o che non gestiscono.

Di seguito sono riportati esempi di app che gestiscono o possiedono reti:

• App degli operatori: gestiscono le reti mobili per le quali il relativo subId dispone dei privilegi dell'operatore
• App di suggerimenti per il Wi-Fi: possiedono reti Wi-Fi che suggeriscono al sistema
• App VPN: gestiscono tutte le reti utilizzate dalla VPN, ma solo quando sono la VPN attiva

I callback vengono richiamati nei seguenti casi:

• Convalida della rete: il sistema ha terminato la valutazione di una rete specifica. La ConnectivityReport classe fornisce informazioni sullo stato attuale della rete e sui risultati di eventuali test o procedure eseguiti nell'ambito della convalida.

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

• Stallo dei dati sospetto: si sospetta uno stallo dei dati, una condizione in cui i pacchetti IP non fluiscono correttamente attraverso la rete. La classe fornisce informazioni sui sospetti stalli dei dati.DataStallReport

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

• Connettività segnalata: un'app ha segnalato la connettività al sistema tramite ConnectivityManager#reportNetworkConnectivity. Vengono condivise la rete e la connettività segnalata (se l'app ritiene che la rete fornisca o meno la connettività).

Implementazione

Per utilizzare l'API Diagnostica della connettività, un'app deve ottenere un ConnectivityDiagnosticsManager istanza dalla piattaforma. Questa istanza deve essere utilizzata per registrare e annullare la registrazione ConnectivityDiagnosticsCallback delle implementazioni. I metodi di callback non sottoposti a override sono autonomi.

Di seguito è riportato un esempio di ConnectivityDiagnosticsCallback implementazione:

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

Per registrare i callback e ricevere notifiche, chiama registerConnectivityDiagnosticsCallback. Per annullare la registrazione dei callback e interrompere la ricezione di notifiche, chiama unregisterConnectivityDiagnosticsCallback.

Di seguito è riportato un esempio di registrazione e annullamento della registrazione di 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);

Convalida

L'API Diagnostica della connettività viene testata da CTS tramite ConnectivityDiagnosticsManagerTest.