ControlChannelTrigger ControlChannelTrigger ControlChannelTrigger ControlChannelTrigger Class

Definition

Enables real time notifications to be received in the background for objects that establish a TCP connection and wish to be notified of incoming traffic.

Note

This class is not supported on Windows Phone.

public : sealed class ControlChannelTrigger : IClosable, IControlChannelTrigger, IControlChannelTrigger2public sealed class ControlChannelTrigger : IDisposable, IControlChannelTrigger, IControlChannelTrigger2Public NotInheritable Class ControlChannelTrigger Implements IDisposable, IControlChannelTrigger, IControlChannelTrigger2// This API is not available in Javascript.
Attributes
Windows 10 requirements
Device family
Windows Desktop Extension SDK (introduced v10.0.10240.0) Windows Mobile Extension SDK (introduced v10.0.10240.0)
API contract
Windows.Networking.Sockets.ControlChannelTriggerContract (introduced v1)

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.

While the ControlChannelTrigger class can be used with DatagramSocket, StreamSocket, or StreamSocketListener, Windows 10 provides an improved mechanism for apps that use those classes and want to maintain connections while in the background. See Network communications in the background for details about SocketActivityTrigger and the socket broker.

The ControlChannelTrigger class is recommended to be used by instances of the following that establish a TCP connection:

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.

Constructors

ControlChannelTrigger(String, UInt32) ControlChannelTrigger(String, UInt32) ControlChannelTrigger(String, UInt32) ControlChannelTrigger(String, UInt32)

Creates a new ControlChannelTrigger object with a control channel trigger ID and a value for the server keep-alive interval.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : ControlChannelTrigger(PlatForm::String channelId, unsigned int serverKeepAliveIntervalInMinutes)public ControlChannelTrigger(String channelId, UInt32 serverKeepAliveIntervalInMinutes)Public Sub New(channelId As String, serverKeepAliveIntervalInMinutes As UInt32)// This API is not available in Javascript.
Parameters
channelId
PlatForm::String String String String

A string used to differentiate various control channel triggers on the local computer. The maximum length allowed for this string is 64 characters.

serverKeepAliveIntervalInMinutes
unsigned int UInt32 UInt32 UInt32

The keep-alive interval, in minutes, registered with the system to indicate when the app and network connections used should wake up.

The minimum value that can be set for this parameter is 15 minutes. The maximum value that can be set is 1439 minutes (approximately 24 hours).

Remarks

The ControlChannelTrigger(String, UInt32) constructor creates a ControlChannelTrigger object. By default, the resource type requested for the control channel trigger is a ControlChannelTriggerResourceType set to RequestSoftwareSlot.

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.

See Also

ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) ControlChannelTrigger(String, UInt32, ControlChannelTriggerResourceType) 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.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : ControlChannelTrigger(PlatForm::String channelId, unsigned int serverKeepAliveIntervalInMinutes, ControlChannelTriggerResourceType resourceRequestType)public ControlChannelTrigger(String channelId, UInt32 serverKeepAliveIntervalInMinutes, ControlChannelTriggerResourceType resourceRequestType)Public Sub New(channelId As String, serverKeepAliveIntervalInMinutes As UInt32, resourceRequestType As ControlChannelTriggerResourceType)// This API is not available in Javascript.
Parameters
channelId
PlatForm::String String String String

A string used to differentiate various control channel triggers on the local computer. The maximum length allowed for this string is 64 characters.

serverKeepAliveIntervalInMinutes
unsigned int UInt32 UInt32 UInt32

The keep-alive interval, in minutes, registered with the system to indicate when the app and network connections used should wake up.

The minimum value that can be set for this parameter is 15 minutes. The maximum value that can be set is 1439 minutes (approximately 24 hours).

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.

See Also

Properties

ControlChannelTriggerId ControlChannelTriggerId ControlChannelTriggerId ControlChannelTriggerId

Gets a string that can be used to differentiate various control channel triggers on the local computer.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : PlatForm::String ControlChannelTriggerId { get; }public string ControlChannelTriggerId { get; }Public ReadOnly Property ControlChannelTriggerId As string// This API is not available in Javascript.
Value
PlatForm::String string string string

A string that can be used to differentiate various control channel triggers.

Remarks

This ControlChannelTriggerId property is set when creating a ControlChannelTrigger object using one of the ControlChannelTrigger constructors. The channelId parameter passed to the constructor sets this property.

CurrentKeepAliveIntervalInMinutes CurrentKeepAliveIntervalInMinutes CurrentKeepAliveIntervalInMinutes CurrentKeepAliveIntervalInMinutes

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; }public uint CurrentKeepAliveIntervalInMinutes { get; }Public ReadOnly Property CurrentKeepAliveIntervalInMinutes As uint// This API is not available in Javascript.
Value
unsigned int uint uint uint

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.

See Also

IsWakeFromLowPowerSupported IsWakeFromLowPowerSupported IsWakeFromLowPowerSupported IsWakeFromLowPowerSupported

Gets a value indicating whether waking from low power states is supported.

public : PlatForm::Boolean IsWakeFromLowPowerSupported { get; }public bool IsWakeFromLowPowerSupported { get; }Public ReadOnly Property IsWakeFromLowPowerSupported As bool// This API is not available in Javascript.
Value
PlatForm::Boolean bool bool bool

If true, then waking from low power states is supported.

Additional features and requirements
Device family
Windows Desktop Extension SDK (introduced v10.0.14393.0) Windows Mobile Extension SDK (introduced v10.0.14393.0)
API contract
Windows.Networking.Sockets.ControlChannelTriggerContract (introduced v2)

KeepAliveTrigger KeepAliveTrigger KeepAliveTrigger KeepAliveTrigger

Gets 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.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : IBackgroundTrigger KeepAliveTrigger { get; }public IBackgroundTrigger KeepAliveTrigger { get; }Public ReadOnly Property KeepAliveTrigger As IBackgroundTrigger// This API is not available in Javascript.
Value
IBackgroundTrigger IBackgroundTrigger IBackgroundTrigger IBackgroundTrigger

A string that represents the activation class ID for the keep-alive background task.

PushNotificationTrigger PushNotificationTrigger PushNotificationTrigger PushNotificationTrigger

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; }public IBackgroundTrigger PushNotificationTrigger { get; }Public ReadOnly Property PushNotificationTrigger As IBackgroundTrigger// This API is not available in Javascript.
Value
IBackgroundTrigger IBackgroundTrigger IBackgroundTrigger IBackgroundTrigger

A string that represents the activation class ID for the push notification background task.

ServerKeepAliveIntervalInMinutes ServerKeepAliveIntervalInMinutes ServerKeepAliveIntervalInMinutes ServerKeepAliveIntervalInMinutes

Get 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.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : unsigned int ServerKeepAliveIntervalInMinutes { get; set; }public uint ServerKeepAliveIntervalInMinutes { get; set; }Public ReadWrite Property ServerKeepAliveIntervalInMinutes As uint// This API is not available in Javascript.
Value
unsigned int uint uint uint

The server keep-alive interval, in minutes, registered with the system to indicate when the app and associated network connections used should wake up.

Remarks

The minimum value that can be set for this property is 15 minutes. The maximum value that can be set for this property is 1439 minutes (approximately 24 hours).

An app should set this to the maximum interval that works with the target network service.

TransportObject TransportObject TransportObject TransportObject

Gets the transport object that the system is using for the transport connection associated with the ControlChannelTrigger object.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : PlatForm::Object TransportObject { get; }public object TransportObject { get; }Public ReadOnly Property TransportObject As object// This API is not available in Javascript.
Value
PlatForm::Object object object object

The transport object that the system is using for the transport connection

Methods

Close() Close() Close() Close()

Closes the ControlChannelTrigger object.

Note

This method is not supported on Windows Phone.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// This API is not available in Javascript.

Remarks

The Close method aborts any pending operations and releases all unmanaged resources associated with the ControlChannelTrigger object. Calling this method frees any hardware resources allocated for the ControlChannelTrigger.

In .NET Framework 4.5, this method is projected as the method. In C++, this method is projected as part of the destructor (delete operator).

DecreaseNetworkKeepAliveInterval() DecreaseNetworkKeepAliveInterval() DecreaseNetworkKeepAliveInterval() 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.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : void DecreaseNetworkKeepAliveInterval()public void DecreaseNetworkKeepAliveInterval()Public Function DecreaseNetworkKeepAliveInterval() As void// This API is not available in Javascript.

Remarks

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

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()

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()public void FlushTransport()Public Function FlushTransport() As void// This API is not available in Javascript.

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.

UsingTransport(Object) UsingTransport(Object) UsingTransport(Object) UsingTransport(Object)

Sets the transport connection to be used by a control channel trigger by class elements in the Windows.Networking.Sockets and related namespaces.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : void UsingTransport(PlatForm::Object transport)public void UsingTransport(Object transport)Public Function UsingTransport(transport As Object) As void// This API is not available in Javascript.
Parameters
transport
PlatForm::Object Object Object Object

The instance of the network class that represents the network transport.

Remarks

The UsingTransport method indicates to the system the transport connection to be used by the ControlChannelTrigger .

An app must call the UsingTransport method after the transport object (a StreamSocket instance, for example) has been created, but before a network connection is established.

For a StreamSocket, the constructor for the StreamSocket would first be called to create the transport object. Then the returned StreamSocket instance would be passed to the UsingTransport method as the transport parameter. Only then can one of the StreamSocket.ConnectAsync methods be called to establish the network connection.

For HttpClient in the Windows.Web.Http namespace, the UsingTransport method needs to be called with the initialized HttpClient instance before any of the GET, PUT, POST, SEND, OR DELETE request methods on the HttpClient or related classes are invoked.

For IXMLHTTPRequest2 interface, the HTTP request must be opened first using the Open method and passed to the UsingTransport method. Then the Send method on the IXMLHTTPRequest2 object can be invoked to send the HTTP request.

For , the UsingTransport method needs to be called with the initialized instance before any of the GET, PUT, POST, SEND, OR DELETE request methods on the or related classes are invoked.

WaitForPushEnabled() WaitForPushEnabled() WaitForPushEnabled() 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.

Note

The ControlChannelTrigger class is not supported on Windows Phone.

public : ControlChannelTriggerStatus WaitForPushEnabled()public ControlChannelTriggerStatus WaitForPushEnabled()Public Function WaitForPushEnabled() As ControlChannelTriggerStatus// This API is not available in Javascript.
Returns

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.

See Also