API di diagnostica della connettività

L'API di diagnostica della connettività consente alle app che possiedono o gestiscono reti, come app dell'operatore, app VPN e app di suggerimenti Wi-Fi, di ricevere informazioni diagnostiche sulla connettività di rete dal framework. Queste app possono registrare richiamate e ricevere notifiche con informazioni sulla connettività per le reti che possiedono o gestiscono. Le app non riceveranno notifiche per le reti che non sono di proprietà o gestite dall'app.

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

• App dell'operatore: gestisci le reti cellulari per le quali il loro subId ha privilegi dell'operatore
• App di suggerimento Wi-Fi: possiedono reti Wi-Fi suggerite al sistema
• App VPN: gestisci tutte le reti utilizzate dalla VPN, ma solo quando sono la VPN attiva

Le richiamate vengono richiamate nei seguenti casi:

• Convalida della rete: il sistema ha terminato la valutazione di una rete specifica. La classe ConnectivityReport fornisce informazioni sullo stato corrente della rete e sui risultati di eventuali test o procedure eseguite come parte della convalida.

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

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

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

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

Implementazione

Per utilizzare l'API Connectivity Diagnostics, un'app deve ottenere un'istanza ConnectivityDiagnosticsManager dalla piattaforma. Questa istanza deve essere utilizzata per registrare e annullare la registrazione delle implementazioni ConnectivityDiagnosticsCallback . I metodi di callback che non vengono sovrascritti sono no-ops.

Di seguito è riportato un esempio di implementazione 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
        ... 
    }
}

Per registrare le richiamate e ricevere notifiche, chiamare registerConnectivityDiagnosticsCallback . Per annullare la registrazione delle richiamate e interrompere la ricezione delle notifiche, chiamare unregisterConnectivityDiagnosticsCallback .

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

Validazione

L'API Connectivity Diagnostics è CTS testata da ConnectivityDiagnosticsManagerTest .