Message​Web​Socket​Control Message​Web​Socket​Control Message​Web​Socket​Control Class

Definition

Provides socket control data on a MessageWebSocket.

public sealed class MessageWebSocketControl : IMessageWebSocketControl, IWebSocketControl, IWebSocketControl2public sealed class MessageWebSocketControl : IMessageWebSocketControl, IWebSocketControl, IWebSocketControl2Public NotInheritable Class MessageWebSocketControl Implements IMessageWebSocketControl, IWebSocketControl, IWebSocketControl2
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The MessageWebSocketControl class provides access to advanced socket control data on a MessageWebSocket object.

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

The SupportedProtocols property gets the value of this property and can be called at any time.

The MessageType property can be changed at any time before or after the MessageWebSocket is connected. This allows an app to switch between binary and UTF-8 messages when needed.

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

Any changes to the other property values on the MessageWebSocketControl must be set before the DatagramSocket is bound or connected. As a result if you need to make changes to the MaxMessageSize, ProxyCredential, OutboundBufferSizeInBytes, or ServerCredential properties, then these changes must occur before a successful call to the ConnectAsync method on the MessageWebSocket.

The following example creates a MessageWebSocket, and then demonstrates how to set the MessageWebSocketControl.MessageType property to binary. (Other properties may be set in a similar manner.) After this is done, the app can connect the MessageWebSocket.

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

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

// Set messageType to binary 
clientWebSocket.control.messageType = Windows.Networking.Sockets.SocketMessageType.binary;

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

using namespace Windows::Networking::Sockets;

MessageWebSocket^ clientWebSocket = ref new MessageWebSocket();

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

// Set messageType to binary 
clientWebSocket->Control->MessageType = SocketMessageType::Binary;

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

MessageWebSocket clientWebSocket = new MessageWebSocket();

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

// Set messageType to binary 
clientWebSocket.Control.MessageType = SocketMessageType.Binary;

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

For more information on using MessageWebSocketControl, see How to use advanced WebSocket controls and How to use advanced WebSocket controls .

Properties

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 IVector<ChainValidationResult> IgnorableServerCertificateErrors { get; }Public ReadOnly Property IgnorableServerCertificateErrors As IVector<ChainValidationResult>
Value

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.

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

Remarks

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 MessageWebSocket();
                myWebSocket.Information.IgnorableServerCertificateErrors.Add(ChainValidationResult.Untrusted);

                ...

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

            }

MaxMessageSize MaxMessageSize MaxMessageSize

The maximum message size, in bytes, for a WebSocket message to be configured on the MessageWebSocket object.

public uint MaxMessageSize { get; set; }public uint MaxMessageSize { get; set; }Public ReadWrite Property MaxMessageSize As uint
Value
uint uint uint

The maximum message size, in bytes, to be configured on the MessageWebSocket object.

Attributes

Remarks

The MaxMessageSize property is used to configure the maximum size of a WebSocket message on a MessageWebSocket object. If a message exceeds this size, MessageReceived event will be raised on the MessageWebSocket object, and the GetDataReader or GetDataStream method on the MessageWebSocketMessageReceivedEventArgs callback parameter will fail (with an error code indicating that the maximum message size has been exceeded).

The default value for the MaxMessageSize property is INFINITE.

The MaxMessageSize property can only be set before calling the ConnectAsync method on the MessageWebSocket object. If the MessageWebSocket is already connected, an attempt to set this property will return an error.

See Also

MessageType MessageType MessageType

The WebSocket message type to be configured on a MessageWebSocket object for write operations.

public SocketMessageType MessageType { get; set; }public SocketMessageType MessageType { get; set; }Public ReadWrite Property MessageType As SocketMessageType
Value
SocketMessageType SocketMessageType SocketMessageType

The WebSocket message type. The default is binary.

Attributes

Remarks

A WebSocket message on the MessageWebSocket object can be either a binary message or a UTF-8 message. The default value is SocketMessageType.Binary.

This property only affects write operations on OutputStream. It does not affect the format of received messages.

The MessageType property can be changed at any time. This allows an app to switch between binary and UTF-8 messages when needed.

Before changing the MessageType on a bound or connected MessageWebSocket, any outgoing packets should first be flushed to ensure that all previously-written data is sent out with the previous message type

See Also

OutboundBufferSizeInBytes OutboundBufferSizeInBytes OutboundBufferSizeInBytes

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

public uint OutboundBufferSizeInBytes { get; set; }public uint OutboundBufferSizeInBytes { get; set; }Public ReadWrite Property OutboundBufferSizeInBytes As uint
Value
uint uint uint

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

Attributes

Remarks

The OutboundBufferSizeInBytes property sets the value of the SO_SNDBUF socket option on the TCP socket used by the MessageWebSocket. 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 MessageWebSocket 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 MessageWebSocket is connected. Setting this property after the MessageWebSocket is connected has no effect.

See Also

ProxyCredential ProxyCredential ProxyCredential

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

public PasswordCredential ProxyCredential { get; set; }public PasswordCredential ProxyCredential { get; set; }Public ReadWrite Property ProxyCredential As PasswordCredential
Value
PasswordCredential PasswordCredential PasswordCredential

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

Attributes

Remarks

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

See Also

ServerCredential ServerCredential ServerCredential

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

public PasswordCredential ServerCredential { get; set; }public PasswordCredential ServerCredential { get; set; }Public ReadWrite Property ServerCredential As PasswordCredential
Value
PasswordCredential PasswordCredential PasswordCredential

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

Attributes

Remarks

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

See Also

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<string> SupportedProtocols { get; }public IVector<string> SupportedProtocols { get; }Public ReadOnly Property SupportedProtocols As IVector<string>
Value

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

Attributes

Remarks

The SupportedProtocols property contains a collection of WebSocket sub-protocols supported by the MessageWebSocket 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 mutually supported sub-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