Skip to main content
ControlChannelTrigger class

Applies to Windows only

Enables real time notifications to be received in the background for class elements in the Windows.Networking.Sockets namespace and other networking transports.

Note  This class is not supported on Windows Phone.

Syntax


public sealed class ControlChannelTrigger : IDisposable

Public NotInheritable Class ControlChannelTrigger
    Implements IDisposable

public ref class ControlChannelTrigger sealed : IClosable

Attributes

[ MarshalingBehavior(Agile)]
[ Threading(MTA)]
[ Version(0x06020000)]
[ WebHostHidden()]

Members

The ControlChannelTrigger class has these types of members:

Constructors

The ControlChannelTrigger class has these constructors.

ConstructorDescription
ControlChannelTrigger(String, UInt32) Creates a new ControlChannelTrigger object with a control channel trigger ID and a value for the server keep-alive interval. The ControlChannelTrigger class is not supported on Windows Phone.
ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) Creates a new ControlChannelTrigger object with a control channel trigger ID, a value for the server keep-alive interval, and the resource type requested for the control channel trigger. The ControlChannelTrigger class is not supported on Windows Phone.

 

Methods

The ControlChannelTrigger class has these methods. It also inherits methods from the Object class.

MethodDescription
Close [C++]Closes the ControlChannelTrigger object. This method is not supported on Windows Phone.
DecreaseNetworkKeepAliveInterval 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. The ControlChannelTrigger class is not supported on Windows Phone.
Dispose [C#, VB]Performs tasks associated with freeing, releasing, or resetting unmanaged resources. The ControlChannelTrigger class is not supported on Windows Phone.
FlushTransport Flushes any networking data used by the transport connection associated with the ControlChannelTrigger to the networking stack. The ControlChannelTrigger class is not supported on Windows Phone.
UsingTransport Sets the transport connection to be used by a control channel trigger by class elements in the Windows.Networking.Sockets and related namespaces. The ControlChannelTrigger class is not supported on Windows Phone.
WaitForPushEnabled Allows an app to notify the system that a connection has been established and the system should complete the internal configuration of the control channel trigger. The ControlChannelTrigger class is not supported on Windows Phone.

 

Properties

The ControlChannelTrigger class has these properties.

PropertyAccess typeDescription

ControlChannelTriggerId

Read-onlyGets a string that can be used to differentiate various control channel triggers on the local computer. The ControlChannelTrigger class is not supported on Windows Phone.

CurrentKeepAliveIntervalInMinutes

Read-onlyGets the network keep-alive interval, in minutes, maintained by low-level network components in the TCP stack based on current network conditions. The ControlChannelTrigger class is not supported on Windows Phone.

KeepAliveTrigger

Read-onlyGets an object that represents the keep-alive trigger associated with the ControlChannelTrigger object that an app should use to bind the activation class with the background broker infrastructure. The ControlChannelTrigger class is not supported on Windows Phone.

PushNotificationTrigger

Read-onlyGets 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. The ControlChannelTrigger class is not supported on Windows Phone.

ServerKeepAliveIntervalInMinutes

Read/writeGet or set the server keep-alive interval, in minutes, registered with the system to indicate when the app and associated network connections used should wake up. The ControlChannelTrigger class is not supported on Windows Phone.

TransportObject

Read-onlyGets the transport object that the system is using for the transport connection associated with the ControlChannelTrigger object. The ControlChannelTrigger class is not supported on Windows Phone.

 

Remarks

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. Control channel triggers are used by long-running network apps to minimize network and system resource usage (an email app that is left running, for example). Network triggers allow an app to drop to a low-power mode for periods of time, 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. These features are commonly used by long-running network apps targeted for mobile devices to extend battery life.

A Windows Store app for Windows 8 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.

The ControlChannelTrigger class can be used by 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 and HttpClientHandler classes in the System.Net.Http namespace in the .NET Framework 4.5. Custom classes that derive from these classes are also supported.
  • 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)

Note  The ControlChannelTrigger class is not supported in a Windows Store app using JavaScript.

  • Applies to Windows Phone

Note  The ControlChannelTrigger is never raised on Windows Phone devices.

There are several types of keep-alive intervals that may relate to network app. 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 KeepAlive property on the StreamSocketControl class allows an app to enable or disable this TCP keep-alive option on a StreamSocket. The default behavior for a StreamSocket is that TCP keep-alive is disabled. The MessageWebSocket, StreamSocketListener, and StreamWebSocket classes do not have an option to enable TCP keep-alive and this option is disabled by default. Similarly, 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 by the constructors to initialize a new ControlChannelTrigger instance. 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.

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

None supported

Namespace

Windows.Networking.Sockets
Windows::Networking::Sockets [C++]

Metadata

Windows.winmd

DLL

Windows.Networking.Sockets.Pushenabledapplication.dll

See also

Other resources
Connecting to a web service
Connecting to network services
Connecting to a WebSocket service
How to set background connectivity options
Troubleshoot and debug network connections
Reference
HttpClient
HttpClientHandler
IXMLHTTPRequest2
MessageWebSocket
IClosable
Object
StreamSocket
StreamWebSocket
System.Net.Http
Samples
Background task sample
ControlChannelTrigger HttpClient sample
ControlChannelTrigger IXMLHTTPRequest2 sample
ControlChannelTrigger StreamSocket sample
ControlChannelTrigger StreamWebSocket sample