API de diagnostic de connectivité

L'API Connectivity Diagnostics permet aux applications qui possèdent ou gèrent des réseaux, telles que les applications d'opérateur, les applications VPN et les applications de suggestion Wi-Fi, de recevoir des informations de diagnostic sur la connectivité réseau de la structure. Ces applications peuvent enregistrer des rappels et recevoir des notifications contenant des informations de connectivité pour les réseaux qu'elles possèdent ou gèrent. Les applications ne recevront pas de notifications pour les réseaux qui ne sont pas détenus ou gérés par l'application.

Voici des exemples d'applications qui gèrent ou possèdent des réseaux :

  • Applications d'opérateur : gérez les réseaux cellulaires pour lesquels leur subId dispose de privilèges d'opérateur pour
  • Applications de suggestion Wi-Fi : possèdent les réseaux Wi-Fi qu'elles suggèrent au système
  • Applications VPN : gérez tous les réseaux utilisés par leur VPN, mais uniquement lorsqu'ils sont le VPN actif

Les rappels sont invoqués dans les cas suivants :

  • Validation du réseau : le système a terminé l'évaluation d'un réseau spécifique. La classe ConnectivityReport fournit des informations sur l'état actuel du réseau et les résultats de tous tests ou procédures effectués dans le cadre de la validation.

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

  • Un blocage des données est suspecté : un blocage des données, une condition dans laquelle les paquets IP ne circulent pas correctement à travers le réseau, est suspecté. La classe DataStallReport fournit des informations sur les blocages de données suspectés.

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

  • Connectivité signalée : une application a signalé la connectivité via ConnectivityManager#reportNetworkConnectivity au système. Le réseau et la connectivité signalée (que l'application pense que le réseau fournit ou non la connectivité) sont partagés.

Mise en œuvre

Pour utiliser l'API Connectivity Diagnostics, une application doit obtenir une instance ConnectivityDiagnosticsManager à partir de la plateforme. Cette instance doit être utilisée pour enregistrer et désinscrire les implémentations ConnectivityDiagnosticsCallback . Les méthodes de rappel qui ne sont pas remplacées ne fonctionnent pas.

Vous trouverez ci-dessous un exemple d’implémentation 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
        ... 
    }
}

Pour enregistrer des rappels et recevoir des notifications, appelez registerConnectivityDiagnosticsCallback . Pour annuler l'enregistrement des rappels et cesser de recevoir des notifications, appelez unregisterConnectivityDiagnosticsCallback .

Vous trouverez ci-dessous un exemple d'enregistrement et de désenregistrement 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);

Validation

L'API Connectivity Diagnostics est testée CTS par ConnectivityDiagnosticsManagerTest .