API Connectivity Diagnostics

L'API Connectivity Diagnostics consente alle app che possiedono o gestiscono reti, ad esempio app operatore, app VPN e app di suggerimenti per il Wi-Fi, di ricevere informazioni diagnostiche sulla connettività di rete dal framework. Queste app possono registrare 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 emittenti che non sono di proprietà o gestite dall'app.

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

• App operatore:gestisci le reti cellulari per le quali il tuo subId dispone dei privilegi di operatore
• App di suggerimento del Wi-Fi: reti Wi-Fi di proprietà 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 di rete: il sistema ha terminato la valutazione di una rete specifica. La classe ConnectivityReport 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 vengono trasmessi correttamente attraverso la rete. La classe DataStallReport fornisce informazioni sui presunti stalli dei dati.

  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. Vengono condivisi la rete e la connettività segnalata (se l'app ritiene che la rete fornisca o meno la connettività).

Implementazione

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

Di seguito è riportato un esempio di implementazione di 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 i richiami 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 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 Diagnostics della connettività è testata dal CTS da ConnectivityDiagnosticsManagerTest.