Quickstart: Retrieving network connection information (Windows Store apps using JavaScript and HTML)

This topic will show you how to retrieve connectivity details and usage information for network connections on a device.

Prerequisites

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

To ensure your Windows Store app is network ready, you must set the capability in the project Package.appxmanifest file. For a definition of each network capability, see How to configure network isolation capabilities.

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 ConnectionProfile your connected Windows Store app can make the right choices when adapting its behavior for changes in a network environment. For more information on registering to be notified of these changes, see Quickstart: Managing 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 offers cost and data plan information that can be used to prevent unexpected carrier service fees. For more information, see Quickstart: Managing metered network cost constraints.

Retrieving connection profiles

First we define a few variables; an instance of NetworkInformation, which defines the methods your app uses to retrieve a ConnectionProfile. Next, an instance of NetworkCostType, which defines possible network cost types expressed by a ConnectionProfile.

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

The NetworkInformation class defines two methods for ConnectionProfile retrieval. The GetInternetConnectionProfile method will return only the profile associated with the Internet connection.

function DisplayInternetConnectionProfileInfo() {
    try {
        var internetProfile = networkInfo.getInternetConnectionProfile();
        mySample.displayStatus(GetConnectionProfileInfo(internetProfile));
    }
    catch (e) {
        mySample.displayError("Exception Caught: " + e + "\n\r");
    }
}

Calling the GetConnectionProfiles method retrieves profiles for all connections currently established on the device, including the Internet connection.

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

                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

From each ConnectionProfile, the following connection information can be accessed:

Data	Supplied By	Description
Connection Cost	ConnectionCost	Provides connection cost information details, including data limit and roaming information.
Cost Type	NetworkCostType	Indicates the cost type of the network currently used by the connection.
Data Plan Status & Usage	DataPlanStatus, DataPlanUsage	Provides usage information specific to the data plan associated with the connection.
Local Usage	DataUsage	Provides local connection usage information.
Network Adapter	NetworkAdapter	Identifies the network adapter that provides connectivity for the connection.

 

When passed a ConnectionProfile, the following example function calls the methods defined by the object to retrieve connection state and usage information.

function GetConnectionProfileInfo(connectionProfile) {

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

        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 Quickstart: Managing connection events and changes in availability.

Related topics

Network Information sample

Quickstart: Managing connection events and changes in availability

How to retrieve connection usage data for a specific period of time

How to retrieve network adapter and locality information

 

 

Build date: 10/30/2012