Remarks

The ControlChannelTrigger class and related interfaces are used to enable your app to use the network when your app is not the foreground app. A Universal Windows app is normally suspended when it is no longer in 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 and the system should wake up the suspended app when network data is received for the app or the server keep-alive timer interval expires. Use control channel triggers when your app needs to maintain a network connection even if it is in the background.

The IXMLHTTPRequest2 interface. The IXMLHTTPRequest2 interface is an extension to XMLHttpRequest object defined in several working drafts published by the World Wide Web Consortium (W3C)

There are several types of keep-alive intervals that may relate to network apps. At the lowest level, an app can set a TCP keep-alive option to send TCP keep-alive packets between a client app and a server to maintain an established TCP connection that is not being used. The HttpClient class and the XMLHttpRequest JavaScript object do not have an option to enable TCP keep-alive and this option is disabled by default. The TCP keep-alive must be disabled in order to use the ControlChannelTrigger class to support background network notifications.

In the context of the ControlChannelTrigger class, there are two other keep-alive intervals that have an impact.

Server keep-alive interval - This refers to a keep-alive interval in minutes that the app registers with the system for how often to be woken up when the app has been suspended. The system will wake up the app based on the value set for this keep-alive interval. This value is represented by the ServerKeepAliveIntervalInMinutes property on a ControlChannelTrigger class and is set as an argument to the ControlChannelTrigger constructor. This value is considered a server keep-alive interval since a network app might normally set this based on known behavior of the server to which the app has established a TCP connection. For example, if it is known that a web server will disconnect and drop TCP connections if there is no data sent by the app for 30 minutes, the network app could set this server keep-alive interval to 25 minutes.

Network keep-alive interval - This refers to an internal keep-alive timer maintained by low-level network components in the TCP stack based on current network conditions. This value represents the value needed by network intermediaries to keep the TCP connection intact. These network intermediaries represent hardware and devices such as network proxies and network address translators. A network app cannot set this value, since this value is determined dynamically by low-level system components in the TCP stack. The internal calculation of the network keep-alive interval does take account of the server keep-alive interval. A network app can indicate to the system that the network keep-alive timer should be decreased if established TCP connections are regularly dropped by calling the DecreaseNetworkKeepAliveInterval method on a ControlChannelTrigger class.

If an app needs a hardware slot to support connected standby, then the ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) constructor should be used to create the ControlChannelTrigger object since this allows an app to specific the requested resource type.

Remarks

The ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) constructor allows an app to create a ControlChannelTrigger object with a specific the resource type requested for the control channel trigger. If an app needs a hardware slot to support connected standby, then the resourceRequestType should be set to RequestHardwareSlot.

Gets the network keep-alive interval, in minutes, maintained by low-level network components in the TCP stack based on current network conditions.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : unsigned int CurrentKeepAliveIntervalInMinutes { get; }

uint32_t CurrentKeepAliveIntervalInMinutes();

public uint CurrentKeepAliveIntervalInMinutes { get; }

Public ReadOnly Property CurrentKeepAliveIntervalInMinutes As uint

Value

uintuint

The network keep-alive interval, in minutes, maintained by low-level network components in the TCP stack based on current network conditions.

Remarks

The CurrentKeepAliveIntervalInMinutes property represents the network keep-alive interval, in minutes, maintained by low-level network components in the TCP stack based on current network conditions. This value represents the value needed by network intermediaries to keep the TCP connection intact. These network intermediaries represent hardware and devices such as network proxies and network address translators. A network app cannot set this value, since this value is determined dynamically by low-level system components in the TCP stack . However, a network app can indicate to the system that the network keep-alive timer should be decreased if established TCP connections are regularly dropped by calling the DecreaseNetworkKeepAliveInterval method on the ControlChannelTrigger class.

Gets an object that represents the push notification trigger associated with the ControlChannelTrigger object that an app should use to bind the activation class with the background broker infrastructure.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : IBackgroundTrigger PushNotificationTrigger { get; }

IBackgroundTrigger PushNotificationTrigger();

public IBackgroundTrigger PushNotificationTrigger { get; }

Public ReadOnly Property PushNotificationTrigger As IBackgroundTrigger

Provides a way for an app to indicate that the network keep-alive interval maintained by the system with network intermediaries to wake up was too long and should be decreased. This method applies to class elements in the Windows.Networking.Sockets and related namespaces.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : void DecreaseNetworkKeepAliveInterval()

void DecreaseNetworkKeepAliveInterval() const;

public void DecreaseNetworkKeepAliveInterval()

Public Function DecreaseNetworkKeepAliveInterval() As void

Remarks

Network intermediaries represent hardware and devices such as proxies and network address translators.

FlushTransport()FlushTransport()FlushTransport()FlushTransport()

Flushes any networking data used by the transport connection associated with the ControlChannelTrigger to the networking stack.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : void FlushTransport()

void FlushTransport() const;

public void FlushTransport()

Public Function FlushTransport() As void

Remarks

The FlushTransport method flushes any networking data used by the transport connection associated with the ControlChannelTrigger to the networking stack. This method is called at the end of a background task. It ensures any networking data that is being sent leaves the process and has a chance to get to networking stack.

A value that indicates if the system was able to complete configuration of a ControlChannelTrigger object.

Remarks

Once an app is connected, it must call the WaitForPushEnabled method in order to enable the system to complete the internal configuration of the control channel trigger. If an app tries to use the network trigger mechanism without calling the WaitForPushEnabled method, it will get an exception.

This call to the WaitForPushEnabled method is to be made only after the transport connection is established.