How to retrieve network connection information (HTML)

This topic shows how to retrieve connectivity details and usage information for network connections on a device using classes in the Windows.Networking.Connectivity namespace.

Prerequisites

The following examples use JavaScript and are based on the Network information sample. For general help creating a Windows Runtime app using JavaScript, see Create your first Windows Runtime app using JavaScript.

What is a connection profile?

A ConnectionProfile represents a single network connection established on a device. The information accessed from a ConnectionProfile can be used to determine the current connectivity level, track data usage, or identify the network adapter used to maintain the connection. By registering to be notified of changes to the properties of a ConnectionProfile, your connected Windows Runtime app can make the right choices when adapting its behavior for changes in a network environment. For more information on registering for these notifications, see How to manage network connection events and changes in availability.

For more specialized scenarios, like connected applications for mobile devices that frequently roam and operate on metered networks, a ConnectionProfile provides cost and data plan information that can be used to prevent unexpected carrier service fees. For more information, see How to manage metered network cost constraints.

Each ConnectionProfile provides access to the following connection information:

Retrieving connection profiles

First define an instance of the NetworkInformation class, which defines the methods your app uses to retrieve a ConnectionProfile. Also define an instance of the NetworkCostType class, which defines possible network cost types associated with a ConnectionProfile.

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

The NetworkInformation class defines two methods for retrieving a ConnectionProfile. If you only need to return the profile associated with the Internet connection, use the getInternetConnectionProfile method.

You must write code to handle exceptions when you call most asynchronous network methods. Also the methods in the Windows.Networking.Connectivity namespace that retrieve a ConnectionProfile can throw exceptions. Your exception handler can retrieve more detailed information on the cause of the exception to better understand the failure and make appropriate decisions. For more information, see How to handle exceptions in network apps.

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");
    }
}

If you want to retrieve profiles for all connections (including the Internet connection), use the getConnectionProfiles method.

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");
      }
}

Accessing information from a connection profile

The following example code calls methods on the ConnectionProfile to retrieve network connection state, cost, and data plan usage information.

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;
}

Summary

In this topic we reviewed how to retrieve connection profiles and the connectivity information that each profile contains. Using this information to help your app make the right choices is essential for a reliable connected experience.

For additional guidelines and best practices for using connection information to guide the behavior of your networked app, see How to manage network connection events and changes in availability.

Related topics

Other

Create your first Windows Runtime app using JavaScript

How to handle exceptions in network apps

How to manage network connection events and changes in availability

How to manage metered network cost constraints

How to retrieve network adapter and locality information

How to retrieve network connection usage data

Reference

ConnectionProfile

DataPlanStatus

NetworkInformation

Windows.Networking.Connectivity

Samples

Network information sample

Network status background sample