Quickstart: Managing connection events and changes in availability (Windows Store apps using JavaScript and HTML)

This topic will show you how to register for connection state change event notifications and retrieve the current state information. We also provide recommendations for app behavior that will support a consistent user experience in network scenarios.

Prerequisites

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

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 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 and when Windows 8 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 into 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 in use.

Taking all of these possibilities into consideration, there is more than enough reason to equip your app with the logic that allows for smart choices when encountering changes to with network availability. Still, 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 code demonstrates registration for notification of NetworkStatusChange events for a specific connection profile.

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

        // register for network status change notifications
        if (!registeredNetworkStatusNotif) {
            var networkInfo.addEventListener("networkstatuschanged", onNetworkStatusChange);
            registeredNetworkStatusNotif = true;
        }
    }
    catch (e) {
        print("An unexpected exception occured: " + e.name + ": " + e.message);
    }
}

Retrieving the connection state change information

When a status change occurs for the Internet connection profile, the following event handler example provides the ConnectionProfile associated with the event and displays the connection status information, which includes the current scope, type, and cost of connectivity as defined by NetworkConnectivityLevel, NetworkTypes, and NetworkCostType.

Now when a status change occurs for the Internet connection profile, the following example function provides the associated ConnectionProfile.

// Event handler for Network Status Change event
function onNetworkStatusChange(sender) {
    try {
        // get the ConnectionProfile that is currently used to connect to the Internet
        var internetProfile = networkInfo.getInternetConnectionProfile();
        if (internetProfile === null) {
            print("Not connected to Internet\n\r");
        }
        else {
            internetProfileInfo += getConnectionProfileInfo(internetProfile) + "\n\r";
            print(internetProfileInfo);
        }
        internetProfileInfo = "";
    }
    catch (e) {
        print("An unexpected exception occured: " + e.name + ": " + e.message);
    }
}

Recommended app behavior when handling connection state changes

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

Note  Advanced developers may also choose to optimize app behavior when retrying network operations. For example, you may want to replace an existing connection with a new connection over a higher speed network. In this scenario, a developer can use the Sockets APIs, like StreamSocketInformation.BandwidthStatistics, to determine if switching to another connection is appropriate.

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 Quickstart: Managing metered network cost constraints.

Related topics

Network Information sample

Quickstart: Retrieving network connection information

Quickstart: Managing metered network cost constraints

Windows.Networking.Connectivity

Build date: 3/11/2013