How to retrieve network connection information (HTML)

Applies to Windows and Windows Phone

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:

DataSupplied ByDescription

Connection Cost

ConnectionCost

Cost details, including data limit and roaming information.

Cost Type

NetworkCostType

Cost type of the network currently used by the connection.

Data Plan Status & Usage

DataPlanStatus, DataPlanUsage

Usage information specific to the data plan associated with the connection.

Local Usage

NetworkUsage

Local connection usage information.

Network Adapter

NetworkAdapter

Network adapter that provides connectivity for the connection.

WLAN and WWAN connection properties

WlanConnectionProfileDetails

WwanConnectionProfileDetails

Provides additional details that are specific to WLAN and WWAN connection profiles.

 

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";
        returnString += "Connected: " + connectionProfile.connected + "\n\r";

        //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

 

 

Show:
© 2014 Microsoft