StreamWebSocketControl StreamWebSocketControl StreamWebSocketControl StreamWebSocketControl Class

Definition

Provides socket control data on a StreamWebSocket object.

public : sealed class StreamWebSocketControl : IStreamWebSocketControl, IWebSocketControl, IWebSocketControl2
public sealed class StreamWebSocketControl : IStreamWebSocketControl, IWebSocketControl, IWebSocketControl2
Public NotInheritable Class StreamWebSocketControl Implements IStreamWebSocketControl, IWebSocketControl, IWebSocketControl2
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
privateNetworkClientServer internetClient

Remarks

The StreamWebSocketControl class provides access to advanced socket control data on a StreamWebSocket object.

A StreamWebSocketControl object is automatically created with the parent StreamWebSocket object. The StreamWebSocket.Control property provides access to the associated StreamWebSocketControl object.

Any changes to the StreamWebSocketControl property values must be set before the StreamWebSocket is connected. As a result if you need to make changes to the NoDelay, OutboundBufferSizeInBytes, ProxyCredential, ServerCredential, or SupportedProtocols properties, then these changes must occur before a successful call to the ConnectAsync method on the StreamWebSocket.

The following example creates a StreamWebSocket, and then demonstrates how to set the StreamWebSocketControl.NoDelay property to false. (Other properties may be set in a similar manner.) After this is done, the app can connect the StreamWebSocket.

var clientWebSocket = new Windows.Networking.Sockets.StreamWebSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting
var currentSetting = clientWebSocket.control.noDelay; 

// Set noDelay to false so that the Nagle algorithm is not disabled
clientWebSocket.control.noDelay = false;

// Now you can call the ConnectAsync method to connect the StreamWebSocket.

using namespace Windows::Networking::Sockets;

StreamWebSocket^ clientWebSocket = ref new StreamWebSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting 
bool currentSetting = clientWebSocket->Control->NoDelay;

// Set NoDelay to false so that the Nagle algorithm is not disabled
clientWebSocket->Control->NoDelay = false;

// Now you can call the ConnectAsync method to connect the StreamWebSocket.
using Windows.Networking.Sockets;

StreamWebSocket clientWebSocket = new StreamWebSocket();

// Get the current setting for this option
// This isn't required, but it shows how to get the current setting
bool currentSetting = clientWebSocket.Control.NoDelay;

// Set NoDelay to false so that the Nagle algorithm is not disabled
clientWebSocket.Control.NoDelay = false;

// Now you can call the ConnectAsync method to connect the StreamWebSocket.

For more information about using StreamWebSocketControl, see How to use advanced WebSocket controls and How to use advanced WebSocket controls .

Properties

ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval

Allows an app to get the actual unsolicited WebSocket PONG interval.

public : TimeSpan ActualUnsolicitedPongInterval { get; }
public TimeSpan ActualUnsolicitedPongInterval { get; }
Public ReadOnly Property ActualUnsolicitedPongInterval As TimeSpan
var timeSpan = streamWebSocketControl.actualUnsolicitedPongInterval;
Value
TimeSpan TimeSpan TimeSpan TimeSpan

System.Timespan

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)
Capabilities
privateNetworkClientServer internetClient

Remarks

This terminology is defined in WebSocket RFC 6455, which is the time between unsolicited Pong control frames sent by the client to the server. The PONG serves as a unidirectional heartbeat and can be used for the client to determine network connection issues.

ClientCertificate ClientCertificate ClientCertificate ClientCertificate

Gets the certificate provided by the client when a secure WebSocket connection has been established.

public : Certificate ClientCertificate { get; set; }
public Certificate ClientCertificate { get; set; }
Public ReadWrite Property ClientCertificate As Certificate
var certificate = streamWebSocketControl.clientCertificate;
streamWebSocketControl.clientCertificate = certificate;
Value
Certificate Certificate Certificate Certificate

The client certificate.

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)
Capabilities
privateNetworkClientServer internetClient

DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval

Allows an app to get and set the desired unsolicited WebSocket PONG interval.

public : TimeSpan DesiredUnsolicitedPongInterval { get; set; }
public TimeSpan DesiredUnsolicitedPongInterval { get; set; }
Public ReadWrite Property DesiredUnsolicitedPongInterval As TimeSpan
var timeSpan = streamWebSocketControl.desiredUnsolicitedPongInterval;
streamWebSocketControl.desiredUnsolicitedPongInterval = timeSpan;
Value
TimeSpan TimeSpan TimeSpan TimeSpan

System.Timespan

Additional features and requirements
Device family
Windows 10 Fall Creators Update (introduced v10.0.16299.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)
Capabilities
privateNetworkClientServer internetClient

Remarks

This terminology is defined in WebSocket RFC 6455, which is the time between unsolicited Pong control frames sent by the client to the server. The PONG serves as a unidirectional heartbeat and can be used for the client to determine network connection issues.

IgnorableServerCertificateErrors IgnorableServerCertificateErrors IgnorableServerCertificateErrors IgnorableServerCertificateErrors

Gets a list of ignorable server certificate errors. Get this list and add ChainValidationResult values for server certificate errors that you wish to ignore during the secure WebSocket (wss:// protocol) server certificate validation process.

public : IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }
public IList<ChainValidationResult> IgnorableServerCertificateErrors { get; }
Public ReadOnly Property IgnorableServerCertificateErrors As IList<ChainValidationResult>
var iList = streamWebSocketControl.ignorableServerCertificateErrors;
Value
IVector<ChainValidationResult> IList<ChainValidationResult> IList<ChainValidationResult> IList<ChainValidationResult>

A list of ChainValidationResult values indicating the server certificate errors to ignore when validating server certificates. By default, the list is empty and all errors cause validation to fail.

Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)
Capabilities
privateNetworkClientServer internetClient

Examples

The following example demonstrates how to ignore the ChainValidationResult.Untrusted error when you are connecting to a server that uses a self-signed certificate. The code adds the appropriate value to the IgnorableServerCertificateErrors list before calling ConnectAsync on the web socket. The server's self-signed certificate will not cause validation to fail, but other errors in validating the server certificate would still result in ConnectAsync failing.

            private async void CreateAndConnectWebSocket()
            {
                var myWebSocket = new StreamWebSocket();
                myWebSocket.Information.IgnorableServerCertificateErrors.Add(ChainValidationResult.Untrusted);

                ...

                await myWebSocket.ConnectAsync(new Uri("wss://contoso.com/wsendpoint1"));

            }

NoDelay NoDelay NoDelay NoDelay

A value that indicates whether the Nagle algorithm is used on a StreamWebSocket object.

public : Platform::Boolean NoDelay { get; set; }
public bool NoDelay { get; set; }
Public ReadWrite Property NoDelay As bool
var bool = streamWebSocketControl.noDelay;
streamWebSocketControl.noDelay = bool;
Value
Platform::Boolean bool bool bool

A value that indicates whether the Nagle algorithm is used on the TCP connection of a StreamWebSocket object.

Remarks

The NoDelay property controls whether Nagle's algorithm is enabled or disabled on a StreamWebSocket object. The default value for the NoDelay property is true.

Nagle's algorithm is a technique to improving the efficiency of TCP/IP networks by reducing the number of packets that are needed to be sent over the network. The algorithm tries to deal with problems caused by an application that repeatedly emits data in small chunks. A TCP packet has a 40-byte header (20 bytes for IP and 20 bytes for TCP). So if an app sends only 4 bytes in a packet, the overhead on the packet data is very large. This can occur for a remote access protocol (telnet or secure shell, for example) where most key presses may generate only a single byte or two of data that is transmitted immediately. Over a slow link, many of these packets may be in transit over the network at the same time. Nagle's algorithm works by combining a number of small outgoing messages, and sending them all at once. When there is a sent packet for which the sender has received no acknowledgment, the sender keeps buffering output until it has a full packet's worth of output. This allows the output to be sent all at once. The impact of applying Nagle's algorithm is to increase the bandwidth at the expense of latency. A well-written app that buffers sends internally should not need to use Nagle's algorithm.

When this property is true, the StreamWebSocket will disable Nagle's algorithm on the TCP connection. This setting reduces the potential delays when sending small messages. When a StreamWebSocket is created, the default value for this property is true.

When this property is false, the StreamWebSocket will enable Nagle's algorithm on the TCP connection. This setting can increase the bandwidth at the expense of latency, but should only be used with caution. There are some adverse side effects possible when Nagle's algorithm is enabled and certain other TCP optimizations are also used.

This property may be set before the StreamWebSocket is connected. After the StreamWebSocket is connected, setting the property will result in an error.

This property sets the value of the TCP_NODELAY socket option on the TCP socket used by the StreamWebSocket .

See Also

OutboundBufferSizeInBytes OutboundBufferSizeInBytes OutboundBufferSizeInBytes OutboundBufferSizeInBytes

The size, in bytes, of the send buffer to be used for sending data on a StreamWebSocket object.

public : unsigned int OutboundBufferSizeInBytes { get; set; }
public uint OutboundBufferSizeInBytes { get; set; }
Public ReadWrite Property OutboundBufferSizeInBytes As uint
var uint = streamWebSocketControl.outboundBufferSizeInBytes;
streamWebSocketControl.outboundBufferSizeInBytes = uint;
Value
unsigned int uint uint uint

The size, in bytes, of the send buffer to be used for sending data.

Remarks

The OutboundBufferSizeInBytes property sets the value of the SO_SNDBUF socket option on the TCP socket used by the StreamWebSocket. The default value is the local computer's default send buffer size. This value varies based on the system memory size. For more detailed information, see SOL_SOCKET Socket Options in the Windows Sockets documentation.

For most apps, this property should not be set since this disables TCP send auto-tuning by the system on this StreamWebSocket object. With TCP send auto-tuning disabled, network throughput is often worse especially on a connections with high latency. So this property should only be used in very specific situations.

The OutboundBufferSizeInBytes property must be set before the StreamWebSocket is connected. Setting this property after the MessageWebSocket is connected has no effect.

See Also

ProxyCredential ProxyCredential ProxyCredential ProxyCredential

The credential to use to authenticate to the proxy server through HTTP header authentication using a StreamWebSocket object.

public : PasswordCredential ProxyCredential { get; set; }
public PasswordCredential ProxyCredential { get; set; }
Public ReadWrite Property ProxyCredential As PasswordCredential
var passwordCredential = streamWebSocketControl.proxyCredential;
streamWebSocketControl.proxyCredential = passwordCredential;
Value
PasswordCredential PasswordCredential PasswordCredential PasswordCredential

The credential to use to authenticate to the proxy server through HTTP header authentication.

Remarks

The ProxyCredential property must be set before calling the ConnectAsync method on the StreamWebSocket object. An attempt to set the ProxyCredential property after calling the ConnectAsync method will result in an error.

See Also

ServerCredential ServerCredential ServerCredential ServerCredential

The credential to use to authenticate to the WebSocket server through HTTP header authentication using a StreamWebSocket object.

public : PasswordCredential ServerCredential { get; set; }
public PasswordCredential ServerCredential { get; set; }
Public ReadWrite Property ServerCredential As PasswordCredential
var passwordCredential = streamWebSocketControl.serverCredential;
streamWebSocketControl.serverCredential = passwordCredential;
Value
PasswordCredential PasswordCredential PasswordCredential PasswordCredential

The credential to use to authenticate to the WebSocket server through HTTP header authentication.

Remarks

The ServerCredential property must be set before calling the ConnectAsync method on the StreamWebSocket object. An attempt to set the ServerCredential property after calling the ConnectAsync method will result in an error.

See Also

SupportedProtocols SupportedProtocols SupportedProtocols SupportedProtocols

Gets a collection that can be used to add a list of supported sub-protocols that will be advertised to the server during the connect handshake.

public : IVector<Platform::String> SupportedProtocols { get; }
public IList<string> SupportedProtocols { get; }
Public ReadOnly Property SupportedProtocols As IList<string>
var iList = streamWebSocketControl.supportedProtocols;
Value
IVector<Platform::String> IList<string> IList<string> IList<string>

A collection that contains the WebSocket sub-protocols supported by the StreamWebSocket object.

Remarks

The SupportedProtocols property contains a collection of WebSocket sub-protocols supported by the StreamWebSocket object. Before calling the ConnectAsync method, additional supported sub-protocol strings can be added to this collection, which will be sent to the server in the "Sec-WebSocket-Protocol" header during the WebSocket handshake. The protocol chosen by the WebSocket server will then be exposed on the Protocol property.

An attempt to add a sub-protocol to this collection after a successful call to ConnectAsync method will not result in an error but the new value is ignored. However, if the ConnectAsync method call or the connect operation completes with an error, an app can update the collection stored in the SupportedProtocols property and retry the ConnectAsync method call and the new value will be applied.

See Also

See Also