API Connectivity Diagnostics

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 suggestions Wi-Fi, de recevoir des informations de diagnostic sur la connectivité réseau à partir du framework. 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 leur appartiennent pas ou qu'elles ne gèrent pas.

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

  • Applications de l'opérateur : gérez les réseaux mobiles pour lesquels leur subId dispose de droits d'accès.
  • Applications de suggestion de réseaux Wi-Fi : réseaux Wi-Fi propres qu'elles suggèrent au système
  • Applications VPN : elles gèrent tous les réseaux utilisés par leur VPN, mais uniquement lorsqu'elles sont le VPN actif.

Les rappels sont appelés dans les cas suivants :

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

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

  • Suspicion de blocage des données : un blocage des données, c'est-à-dire une situation dans laquelle les paquets IP ne circulent pas correctement sur le réseau, est suspecté. La classe DataStallReport fournit des informations sur les blocages de données suspects.

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

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

Implémentation

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

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 ne plus recevoir de notifications, appelez unregisterConnectivityDiagnosticsCallback.

Vous trouverez ci-dessous un exemple d'enregistrement et d'annulation de l'enregistrement de 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 par la CTS : ConnectivityDiagnosticsManagerTest.