ControlChannelTrigger ControlChannelTrigger ControlChannelTrigger Class

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.

Syntax

Declaration

public sealed class ControlChannelTriggerpublic sealed class ControlChannelTriggerPublic NotInheritable Class ControlChannelTrigger

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 summary

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.

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.

Properties summary

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.

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.

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

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.

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.

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.

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.

Methods summary

Closes the ControlChannelTrigger object.

Note

This method is not supported on Windows Phone.

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.

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.

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.

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.

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(String channelId, UInt32 serverKeepAliveIntervalInMinutes)public New(String channelId, UInt32 serverKeepAliveIntervalInMinutes)Public Sub New(channelId As String, serverKeepAliveIntervalInMinutes As UInt32)public ControlChannelTrigger(String channelId, UInt32 serverKeepAliveIntervalInMinutes)

    Parameters

    • channelId
      System.String
      System.String
      System.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
      System.UInt32
      System.UInt32
      System.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 @Windows.Networking.Sockets.ControlChannelTrigger.#ctor(System.String,System.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 @Windows.Networking.Sockets.ControlChannelTrigger.#ctor(System.String,System.UInt32,Windows.Networking.Sockets.ControlChannelTriggerResourceType) constructor should be used to create the ControlChannelTrigger object since this allows an app to specific the requested resource type.

  • 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(String channelId, UInt32 serverKeepAliveIntervalInMinutes, ControlChannelTriggerResourceType resourceRequestType)public New(String channelId, UInt32 serverKeepAliveIntervalInMinutes, ControlChannelTriggerResourceType resourceRequestType)Public Sub New(channelId As String, serverKeepAliveIntervalInMinutes As UInt32, resourceRequestType As ControlChannelTriggerResourceType)public ControlChannelTrigger(String channelId, UInt32 serverKeepAliveIntervalInMinutes, ControlChannelTriggerResourceType resourceRequestType)

    Parameters

    • channelId
      System.String
      System.String
      System.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
      System.UInt32
      System.UInt32
      System.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).

    • resourceRequestType

      The resource type requested for the control channel trigger.

    Remarks

    The @Windows.Networking.Sockets.ControlChannelTrigger.#ctor(System.String,System.UInt32,Windows.Networking.Sockets.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.

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 string ControlChannelTriggerId { get; }public string ControlChannelTriggerId { get; }Public ReadOnly Property ControlChannelTriggerId As stringpublic string ControlChannelTriggerId { get; }

    Property Value

    • 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 @Windows.Networking.Sockets.ControlChannelTrigger.#ctor(System.String,System.UInt32,Windows.Networking.Sockets.ControlChannelTriggerResourceType) 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 uint CurrentKeepAliveIntervalInMinutes { get; }public uint CurrentKeepAliveIntervalInMinutes { get; }Public ReadOnly Property CurrentKeepAliveIntervalInMinutes As uintpublic uint CurrentKeepAliveIntervalInMinutes { get; }

    Property Value

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

  • IsWakeFromLowPowerSupported
    IsWakeFromLowPowerSupported
    IsWakeFromLowPowerSupported
    IsWakeFromLowPowerSupported

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

    public bool IsWakeFromLowPowerSupported { get; }public bool IsWakeFromLowPowerSupported { get; }Public ReadOnly Property IsWakeFromLowPowerSupported As boolpublic bool IsWakeFromLowPowerSupported { get; }

    Property Value

    • bool
      bool
      bool

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

  • 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 IBackgroundTriggerpublic IBackgroundTrigger KeepAliveTrigger { get; }

    Property Value

  • 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 IBackgroundTriggerpublic IBackgroundTrigger PushNotificationTrigger { get; }

    Property Value

  • 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 uint ServerKeepAliveIntervalInMinutes { get; set; }public uint ServerKeepAliveIntervalInMinutes { get; set; }Public ReadWrite Property ServerKeepAliveIntervalInMinutes As uintpublic uint ServerKeepAliveIntervalInMinutes { get; set; }

    Property Value

    • 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 object TransportObject { get; }public object TransportObject { get; }Public ReadOnly Property TransportObject As objectpublic object TransportObject { get; }

    Property Value

    • 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()public void Close()Public Function Close() As voidpublic void Close()

    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 voidpublic void DecreaseNetworkKeepAliveInterval()

    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()public void FlushTransport()Public Function FlushTransport() As voidpublic void FlushTransport()

    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(Object transport)public void UsingTransport(Object transport)Public Function UsingTransport(transport As Object) As voidpublic void UsingTransport(Object transport)

    Parameters

    • transport
      System.Object
      System.Object
      System.Object

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

    Remarks

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

    An app must call the UsingTransport(Object) 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(Object) method as the transport parameter. Only then can one of the ConnectAsync(EndpointPair) methods be called to establish the network connection.

    For HttpClient in the Windows.Web.Http namespace, the UsingTransport(Object) 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(Object) method. Then the Send method on the IXMLHTTPRequest2 object can be invoked to send the HTTP request.

    For , the UsingTransport(Object) 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 ControlChannelTriggerStatuspublic ControlChannelTriggerStatus WaitForPushEnabled()

    Returns

    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.

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)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute
Windows.Foundation.Metadata.ThreadingAttribute
Windows.Foundation.Metadata.WebHostHiddenAttribute

Details

Assembly

Windows.Networking.Sockets.dll