How to manage network connection events and changes in availability (HTML)

This topic shows how to register to receive notifications for network connection state changes and retrieve the current state information using classes in the Windows.Networking.Connectivity namespace.

We also provide recommendations for app behavior that will support a consistent user experience in network scenarios.

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.

Knowing what a ConnectionProfile is and how to access the information that it represents is important; for more information see How to retrieve network connection information. For additional code examples, download the Network Information sample.

What qualifies as a connection state change event?

State change events indicate changes in the availability, type, or cost of connectivity offered by an individual connection. The latest connected apps frequently encounter network traversal scenarios typical of mobile device usage. When the Windows Runtime detects a new network, it will automatically provide it as a new connectivity option. For instance, if a user is using a device on a 3G/4G network to stream data, and later comes in range of a Wi-Fi network, the new connectivity option will be available for the application to leverage. Of course, this also means that a user can move out the range of a network, one that may even be currently in use.

Taking all of these possibilities into consideration, it is important to equip your app with logic that allows for smart choices when encountering changes in network availability. Existing network connections will not automatically switch over to other connections seamlessly. Your app needs to register for networkstatuschanged events and adapt accordingly.

Registering for notifications of connection state change events

Before your app can adapt to changing network states it needs to know when they occur. The following example code shows how to register for event notifications for networkstatuschanged for a specific connection profile.

You must write code to handle exceptions when you call most asynchronous network methods. Also the methods in the Windows.Networking.Connectivity namespace that register for event notifications or tries to 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.

// Define some variables used

// A variable to store network status change information
var internetProfileInfo = "";

// A  boolean to keep track of registration for network status change notifications
var registeredNetworkStatusNotif = false;

var networkInfo = Windows.Networking.Connectivity.NetworkInformation;

//Register for Network Status Change notifications, and display new Internet Connection Profile information on network status change
function registerForNetworkStatusChangeNotif() {

    // register for network status change notifications
    if (!registeredNetworkStatusNotif) {
        try {
            networkInfo.addEventListener("networkstatuschanged", onNetworkStatusChange);
            registeredNetworkStatusNotif = true;

            if (internetProfileInfo === "") {
                mySample.displayStatus("No network status change. ", "sample", "status");
        }
        catch (e) {
            mySample.displayError("An unexpected exception occured: " + e.name + ": " + e.message);
        }
    }
}

When a network scenario changes, your app may need to unregister from network status change notifications if already registered and then re-register for notifications for the new network scenario.

//Unregister for Network Status Change notifications
function unRegisterForNetworkStatusChangeNotif() {
    try {
        networkInfo.removeEventListener("networkstatuschanged", onNetworkStatusChange);
        internetProfileInfo = "";
    }
    catch (e) {
        mySample.displayError("An unexpected exception occured: " + e.name + ": " + e.message, "sample", "error");
    }
}

Retrieving the connection state change information

When a status change occurs, the following example of an event handler retrieves the associated ConnectionProfile for the current Internet connection profile. This ConnectionProfile can be used to retrieve and display connection status information, which includes the current scope, type, and cost of connectivity as defined by NetworkConnectivityLevel, NetworkTypes, and NetworkCostType.

// Event handler for Network Status Change event
function onNetworkStatusChange(sender) {

    //network status changed
    internetProfileInfo = "Network Status Changed: \n\r";

    try {
        // get the ConnectionProfile that is currently used to connect to the Internet
        var internetProfile = networkInfo.getInternetConnectionProfile();
        if (internetProfile === null) {
            mySample.displayStatus("Not connected to Internet\n\r");
        }
        else {
            internetProfileInfo += getConnectionProfileInfo(internetProfile) + "\n\r";
            mySample.displayStatus(internetProfileInfo);
        }
        internetProfileInfo = "";
    }
    catch (e) {
            mySample.displayError("An unexpected exception occured: " + e.name + ": " + e.message, "sample", "error");
    }
}

There are a variety of network states that can change which result in a network state change event. These include whether the device has a new ConnectionProfile, a new connection cost, connectivity level, and other changes. The above event handler can use the NetworkStateChangeEventDetails class to determine what has changed.

Recommended app behavior when handling connection state changes

The following table outlines the primary connection state change scenarios and provides app behavior recommendations:

Summary

In this topic, we reviewed how to register for connection state change notifications and use these notifications to retrieve the current state information from the ConnectionProfile for which the event occurred. We also reviewed recommended app behavior when dealing with the most common state change scenarios.

While this topic covers network availability, in scenarios involving connections to metered networks, a networkstatuschanged event can also represent a change to the cost and data plan properties. For more information and guidance on how best to change app behavior in these scenarios, see How to manage metered network cost constraints.

Related topics

Other

Create your first Windows Runtime app using JavaScript

How to handle exceptions in network apps

How to manage metered network cost constraints

How to retrieve network adapter and locality information

How to retrieve network connection information

How to retrieve network connection usage data

Reference

ConnectionProfile

NetworkInformation

networkstatuschanged

networkStatusChangedEventHandler

Windows.Networking.Connectivity

Samples

Network information sample

Network status background sample