API Connectivity Diagnostics

L'API Connectivity Diagnostics consente alle app che possiedono o gestiscono reti, come app di operatori, app VPN e app di suggerimenti Wi-Fi, di ricevere dal framework informazioni diagnostiche sulla connettività di rete. Queste app possono registrare callback e ricevere notifiche con informazioni sulla connettività per le reti di loro proprietà o gestite. 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 dell'operatore: gestisci le reti cellulari per le quali il tuo subId ha i privilegi dell'operatore
• App di suggerimento Wi-Fi: reti Wi-Fi di tua proprietà che suggeriscono al sistema
• App VPN: gestiscono tutte le reti utilizzate dalla VPN, ma solo quando è attiva

I richiami vengono invocati nei seguenti casi:

• Convalida della rete: il sistema ha completato 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;
  }
  

• Sospetto blocco dei dati: è sospetto un blocco dei dati, una condizione in cui i pacchetti IP non passano correttamente attraverso la rete. La classe DataStallReport fornisce informazioni su sospette interruzioni 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. La rete e la connettività segnalata (indipendentemente dal fatto che l'app ritenga che la rete fornisca o meno connettività) sono condivise.

Implementazione

Per utilizzare l'API Diagnostica 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 che non vengono sostituiti sono no-op.

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 registrazioneConnectivityDiagnosticsCallback:

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 Connectivity Diagnostics è stata testata da CTS da ConnectivityDiagnosticsManagerTest.