The sample shows how to use the ControlChannelTrigger class to enable a Windows Store app using a TCP StreamSocket so that the app is always connected and always reachable. This sample demonstrates the use of background network notifications in a Windows Store app.
The ControlChannelTrigger class and related interfaces are used to enable real-time network status and triggers for class elements in the Windows.Networking.Sockets and related namespaces. These features allow an app to receive notifications while the app is suspended. These notifications can be set to occur when network packets are received or to maintain keep-alive packets. This sample uses notifications to receive incoming network packets. This allows the app to minimize power usage for improved battery life and wake up to respond to incoming packets and other conditions only when needed.
The ControlChannelTrigger class is commonly used by long-running network apps to minimize network and system resource usage (an email application that is left running, for example). Network triggers allow an app to drop to a low-power mode for periods of time while still keeping established network connections intact and operating in a low-power state. An app can set a server keep-alive interval used by the system for when the app should wake up. An app can also set a trigger to wake up when network data is received by the system for the app.
A Windows Store app for Windows 8.1 is normally suspended when it's no longer the foreground app and moved to the background. There are some exceptions to suspending an app (actively printing, accessing an audio stream, and transferring files in the background, for example). The ControlChannelTrigger class allows a network app that has established a TCP connection to notify the system that an established network connection should be kept operational. Additionally, the system should wake up the suspended app when network data is received for the app or the server keep-alive timer interval expires.
In this sample, the ControlChannelTrigger class is used with the StreamSocket class to connect to network service (another app listening for TCP connections). However, the ControlChannelTrigger class can also be used with other network transports that establish a TCP connection.
The ControlChannelTrigger class can be used with instances of the following classes in the Windows.Networking.Sockets that establish a TCP connection.
The ControlChannelTrigger class can also be used by instances of the following that establish a TCP connection:
- The HttpClient class in the Windows.Web.Http namespace.
- The IXMLHTTPRequest2 interface that extends the IXmlHttpRequest interface defined in several working drafts published by the World Wide Web Consortium (W3C) .
Note The ControlChannelTrigger class is not supported in a Windows Store app built for Windows using JavaScript.
Versions of this sample are provided in both C# and C++. This sample requires some experience with network programming.
This sample requires the following capabilities:
- Home or work networking - Needed when requests are sent over TCP on a home or work intranet.
To obtain an evaluation copy of Windows 8.1, go to Windows 8.1.
To obtain an evaluation copy of Microsoft Visual Studio 2013, go to Visual Studio 2013.
Note For Windows 8 app samples, download the Windows 8 app samples pack. The samples in the Windows 8 app samples pack will build and run only on Microsoft Visual Studio 2012.
Related topics
- Other resources
- Adding support for networking
- Connecting to network services (Windows Store apps using C#/VB/C++ and XAML)
- How to configure network isolation capabilities
- How to set background connectivity options
- Making network connections with sockets
- Supporting your app with background tasks
- Reference
- ControlChannelTrigger
- StreamSocket
- Windows.Networking.Sockets
- Samples
- ControlChannelTrigger HttpClient sample
- ControlChannelTrigger IXMLHTTPRequest2 sample
- ControlChannelTrigger StreamWebSocket sample
- StreamSocket sample
- Windows 8 app samples
Operating system requirements
| Client | |
|---|---|
| Server |
Build the sample
- Start Visual Studio 2013 and select File > Open > Project/Solution.
- Go to the directory in which you unzipped the sample. Go to the directory named for the sample, and double-click the Visual Studio 2013 Solution (.sln) file.
- Press F7 or use Build > Build Solution to build the sample.
Run the sample
This sample requires two computers that can connect to each other using networking. Both computers need to be running Windows 8.1. One computer will play the role of the client, while the other computer will play the role of the server.
To deploy this sample after building it, select Deploy Solution from the Build menu. A tile for the sample will be available on the Start Screen. To both deploy and run the sample, press F5 (run with debugging enabled) or Ctrl+F5 (run without debugging enabled) from Visual Studio 2013 (any SKU). (Or select the corresponding options from the Debug menu.)
The sample must be deployed to both the client and server computers.
To run the sample, first the start the app on the server computer.
- 1. Select the function as the server.
- 2. Enter a TCP port number (port 12345, for example) to start listening for a client connection.
After the server computer has started, start the app on the client computer.
- 1. Select the function as the client.
- 2. Enter the hostname and TCP port on the server computer for the client to connect to (TCP port 12345, for example) and click Connect.
The server computer should show the client as connected. After the client is connected, the server can send a message to the client. The message is received on the client and displayed as a toast notification.
You should be able to let the client app get suspended and it can still receive an incoming network message from the server and display a toast when a message is received.
Note When the app is run under a debugger, it will not be suspended.