Comment récupérer des informations de connexion réseau (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Cette rubrique montre comment récupérer les informations de connectivité et d’utilisation pour les connexions réseau d’un appareil, à l’aide des classes de l’espace de noms Windows.Networking.Connectivity.

Prérequis

Les exemples suivants utilisent JavaScript et s’appuient sur l’exemple d’informations réseau. Pour obtenir une aide générale sur la création d’une application Windows Runtime en JavaScript, voir Créer votre première application Windows Runtime en JavaScript.

Qu’est-ce qu’un profil de connexion ?

Un objet ConnectionProfile représente une connexion réseau particulière établie sur un périphérique. Les informations accessibles dans un objet ConnectionProfile peuvent être utilisées pour déterminer le niveau de connectivité actuel, effectuer le suivi de l’utilisation des données ou identifier la carte réseau utilisée par une connexion. Si votre application Windows Runtime est inscrite pour être informée des modifications apportées aux propriétés de ConnectionProfile, une fois connectée, elle peut effectuer les choix appropriés quand elle adapte son comportement aux modifications d’un environnement réseau. Pour plus d’informations sur l’inscription à ces notifications, voir Comment gérer les événements de connexion réseau et les changements de disponibilité.

Dans des scénarios plus spécifiques, comme celui d’applications connectées pour les appareils mobiles qui sont souvent itinérants et fonctionnent sur des connexions réseau limitées, un objet ConnectionProfile offre des informations sur le coût et le forfait données qui peuvent être utilisées pour éviter des frais de service opérateur imprévus. Pour plus d’informations, voir Comment gérer les contraintes liées au coût des connexions réseau limitées.

Chaque ConnectionProfile permet d’accéder aux informations de connexion suivantes :

Données	Fournies par	Description
Coût de connexion	ConnectionCost	Informations détaillées sur le coût, notamment des informations sur la limite de données et l’itinérance.
Type de coût	NetworkCostType	Type de coût du réseau actuellement utilisé par la connexion.
Statut et utilisation du forfait données	DataPlanStatus, DataPlanUsage	Informations d’utilisation spécifiques au forfait données associé à la connexion.
Utilisation locale	NetworkUsage	Informations d’utilisation de la connexion locale.
Carte réseau	NetworkAdapter	Carte réseau qui assure la connectivité de la connexion.
Propriétés de connexion WLAN et WWAN	WlanConnectionProfileDetails WwanConnectionProfileDetails	Fournit des détails supplémentaires propres aux profils de connexion WLAN et WWAN.

Récupération de profils de connexion

En premier lieu, définissez une instance de la classe NetworkInformation, qui définit les méthodes utilisées par votre application pour récupérer ConnectionProfile. Définissez également une instance de la classe NetworkCostType, qui définit les types de coût réseau possibles associés à ConnectionProfile.

var networkInfo = Windows.Networking.Connectivity.NetworkInformation;
var networkCostInfo = Windows.Networking.Connectivity.NetworkCostType;

La classe NetworkInformation définit deux méthodes de récupération de ConnectionProfile. Si vous devez uniquement retourner le profil associé à la connexion Internet, utilisez la méthode getInternetConnectionProfile.

Vous devez écrire du code capable de gérer les exceptions au moment où vous appelez la plupart des méthodes réseau asynchrones. En outre, les méthodes de l’espace de noms Windows.Networking.Connectivity qui récupèrent ConnectionProfile peuvent lever des exceptions. Votre gestionnaire d’exceptions peut récupérer des informations plus détaillées sur la cause de l’exception dans le but d’analyser l’échec et de prendre des décisions appropriées. Pour plus d’informations, voir Comment gérer les exceptions dans les applications réseau.

function displayInternetConnectionProfileInfo() {
    try {
        // get the ConnectionProfile that is currently used to connect to the Internet
        var internetProfile = networkInfo.getInternetConnectionProfile();
        mySample.displayStatus(GetConnectionProfileInfo(internetProfile));
    }
    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }
}

Si vous souhaitez récupérer les profils de toutes les connexions (notamment la connexion Internet), utilisez la méthode getConnectionProfiles.

function displayConnectionProfileList() {
  var profileList = "";
  try {
      var ConnectionProfiles = networkInfo.getConnectionProfiles();
      if (ConnectionProfiles.length != 0) {
          for (var i = 0; i < ConnectionProfiles.length; i++) {

              //Display Connection profile info for each profile
              profileList += GetConnectionProfileInfo(ConnectionProfiles[i]);
              profileList += "-----------------------------------------\n\r";
          }
          mySample.displayStatus(profileList);
          }
          else {
              mySample.displayStatus("No profiles found");
          }
      }

      catch (e) {
         mySample.displayError("Exception Caught: " + e + "\n\r");
      }
}

Accès aux informations depuis un profil de connexion

L’exemple de code suivant appelle des méthodes sur ConnectionProfile pour récupérer des informations sur l’état de la connexion réseau, le coût et l’utilisation du forfait données.

function getConnectionProfileInfo(connectionProfile) {

    if (connectionProfile == null) {
        return "";
    }

    try {
        var returnString = "ProfileName: " + connectionProfile.profileName + "\n\r";

        switch (connectionProfile.getNetworkConnectivityLevel()) {
            case networkConnectivityInfo.none:
                returnString += "Connectivity Level: None\n\r";
                break;
            case networkConnectivityInfo.localAccess:
                returnString += "Connectivity Level: Local Access\n\r";
                break;
            case networkConnectivityInfo.constrainedInternetAccess:
                returnString += "Connectivity Level: Constrained Internet Access\n\r";
                break;
            case networkConnectivityInfo.internetAccess:
                returnString += "Connectivity Level: Internet Access\n\r";
                break;
        }

        //Display Connection cost info
        returnString += "Connection Cost Information:\n\r";
        returnString += "===============\n\r";
        var connectionCost = connectionProfile.getConnectionCost();
        returnString += "Cost Type: " + GetCostType(connectionCost.networkCostType) + "\n\r";
        returnString += "Roaming: " + connectionCost.roaming + "\n\r";
        returnString += "Over Datalimit: " + connectionCost.overDataLimit + "\n\r";
        returnString += "Approaching Datalimit: " + connectionCost.approachingDataLimit + "\n\r";

        //Display Dataplan status info
        returnString += "Dataplan Status Information:\n\r";
        returnString += "===============\n\r";
        var dataPlanStatus = connectionProfile.getDataPlanStatus();
        if (dataPlanStatus.dataPlanUsage != null) {
            returnString += "Usage In Megabytes: " + dataPlanStatus.dataPlanUsage.megabytesUsed + "\n\r";
            returnString += "Last Sync Time: " + dataPlanStatus.dataPlanUsage.lastSyncTime + "\n\r";
        }
        else {
            returnString += "Dataplan Usage: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.InboundBitsPerSecond != null) {
            returnString += "Inbound Bits Per Second: " + dataPlanStatus.InboundBitsPerSecond + "\n\r";
        }
        else {
            returnString += "Inbound Bits Per Second: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.OutboundBitsPerSecond != null) {
            returnString += "Outbound Bits Per Second: " + dataPlanStatus.OutboundBitsPerSecond + "\n\r";
        }
        else {
            returnString += "Outbound Bits Per Second: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.dataLimitInMegabytes != null) {
            returnString += "Data Limit In Megabytes: " + dataPlanStatus.dataLimitInMegabytes + "\n\r";
        }
        else {
            returnString += "Data Limit In Megabytes: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.nextBillingCycle != null) {
            returnString += "Next Billing Cycle: " + dataPlanStatus.nextBillingCycle + "\n\r";
        }
        else {
            returnString += "Next Billing Cycle: " + "Not Defined" + "\n\r";
        }

        if (dataPlanStatus.maxDownloadFileSizeInMegabytes != null) {
            returnString += "Maximum Download File Size in Megabytes: " + dataPlanStatus.maxDownloadFileSizeInMegabytes + "\n\r";
        }
        else {
            returnString += "Maximum Download File Size in Megabytes: " + "Not Defined" + "\n\r";
        }
            returnString += "Cost Based Suggestions: " + CostBasedSuggestions(connectionCost) + "\n\r";
        }

    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }

    return returnString;
}

Récapitulatif

Dans cette rubrique, nous avons vu comment récupérer des profils de connexion et les informations de connectivité que chaque profil contient. L’utilisation de ces informations pour aider votre application à faire les bons choix est essentielle pour garantir la fiabilité de l’expérience connectée.

Pour obtenir des instructions supplémentaires ou les meilleures pratiques préconisées pour l’utilisation des informations de connexion pour guider le comportement de votre application réseau, voir Comment gérer les événements de connexion réseau et les changements de disponibilité.