MICROSOFT_PRESS_EBOOK_PROGRAMMING_WINDOWS_8_APPS_WITH_HTML_CSS_AND_JAVASCRIPT_PDF

The ConnectionProfile Object
Of all the information available through the NetworkInformation object, the most important for apps is
found in ConnectionProfile, most frequently that returned by getInternetConnection-Profile
because that’s the one through which an app’s Internet traffic will flow. The profile is what contains all
the information you need to make decisions about how you’re using the network, especially for cost
awareness. It’s also what you’ll typically check when there’s a change in network status. Scenarios 1 and
3 of the Network information sample retrieve and display most of these details.
Each profile has a profileName property (a string), such as “Ethernet” or the SSID of your wireless
access point, plus a getNetworkNames method that returns a vector of friendly names for the endpoint.
The networkAdapter property contains a NetworkAdapter object for low-level details, should you want
them, and the networkSecuritySettings property contains a NetworkSecurity-Settings object
properties describing authentication and encryption types.
More generally interesting is the getNetworkConnectivityLevel, which returns a value from the
NetworkConnectivityLevel enumeration: none (no connectivity), localAccess (the level you hate to
see when you’re trying to get a good connection!), constrainedInternetAccess (captive portal
connectivity, typically requiring further credentials as is often encountered in hotels, airports, etc.), and
internetAccess (the state you’re almost always trying to achieve). The connectivity level is often a factor
in your app logic and something you typically watch with network status changes.
To track the inbound and outbound traffic on a connection, the getLocalUsage method returns a
DataUsage object that contains bytesReceived and bytesSent, either for the lifetime of the connection
or for a specific time period. Similarly, the getConnectionCost and getDataPlanStatus provide the
information an app needs to be aware of how much network traffic is happening and how much it
might cost the user. We’ll come back to this in “Cost Awareness” shortly, including how to see per-app
usage in Task Manager.
Connectivity Events
It is very common for a running app to want to know when connectivity changes. This way it can take
appropriate steps to disable or enable certain functionality, alert the user, synchronize data after being
offline, and so on. For this, apps need only watch the NetworkInformation.onnetworkstatus-changed
event, which is fired whenever there’s a significant change within the hierarchy of objects we’ve just
seen (and be mindful that this event comes from a WinRT object). For example, the event will be fired if
the connectivity level of a profile changes. It will also be fired if the Internet profile itself changes, as
when a device roams between different networks, or when a metered data plan is approaching or has
exceeded its limit, at which point the user will start worrying about every megabyte of traffic. In short,
you’ll generally want to listen for this event to refresh any internal state of your app that’s dependent on
network characteristics and set whatever flags you use to configure the app’s networking behavior. This
is especially important for transitioning between online and offline and between unlimited and metered
networks; Windows, for its part, also watches this event to adjust its own behavior, as with the
Background Transfer APIs.
634