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 ni ne sont gérés par elles.

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

  • Applications d'opérateurs:permettent de gérer les réseaux mobiles pour lesquels leur subId dispose de droits d'opérateur
  • Applications de suggestion de réseaux Wi-Fi:réseaux Wi-Fi qu'elles suggèrent au système
  • Applications VPN: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 de tous les 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, une condition dans laquelle les paquets IP ne circulent pas correctement sur le réseau, est suspecté. La classe DataStallReport fournit des informations sur les arrêts 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é la connectivité au système via ConnectivityManager#reportNetworkConnectivity. Le réseau et la connectivité signalée (que 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 annuler l'enregistrement des implémentations ConnectivityDiagnosticsCallback. Les méthodes de rappel qui ne sont pas remplacées ne sont pas exécutées.

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 ConnectivityDiagnosticsManagerTest dans CTS.