MessageWebSocketControl MessageWebSocketControl MessageWebSocketControl MessageWebSocketControl Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

[Contains prerelease APIs.]
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// You can use this class in JavaScript.
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

ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval ActualUnsolicitedPongInterval

Prerelease. 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// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

System.Timespan

Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16257.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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

Prerelease. 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// You can use this property in JavaScript.
Value
Certificate Certificate Certificate Certificate

The client certificate.

Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16257.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval DesiredUnsolicitedPongInterval

Prerelease. 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// You can use this property in JavaScript.
Value
TimeSpan TimeSpan TimeSpan TimeSpan

System.Timespan

Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16257.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)

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>// You can use this property in JavaScript.
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)

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 MaxMessageSize

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

public : unsigned int MaxMessageSize { get; set; }public uint MaxMessageSize { get; set; }Public ReadWrite Property MaxMessageSize As uint// You can use this property in JavaScript.
Value
unsigned int uint uint uint

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

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 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// You can use this property in JavaScript.
Value
SocketMessageType SocketMessageType SocketMessageType SocketMessageType

The WebSocket message type. The default is binary.

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 OutboundBufferSizeInBytes

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

public : unsigned int OutboundBufferSizeInBytes { get; set; }public uint OutboundBufferSizeInBytes { get; set; }Public ReadWrite Property OutboundBufferSizeInBytes As uint// You can use this property in JavaScript.
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 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 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// You can use this property in JavaScript.
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 MessageWebSocket object. An attempt to set the ProxyCredential property after calling the ConnectAsync method will result in an error.

See Also

ReceiveMode ReceiveMode ReceiveMode ReceiveMode

Prerelease. Allows clients to control receiving either complete or partial messages.

public : MessageWebSocketReceiveMode ReceiveMode { get; set; }public MessageWebSocketReceiveMode ReceiveMode { get; set; }Public ReadWrite Property ReceiveMode As MessageWebSocketReceiveMode// You can use this property in JavaScript.
Additional features and requirements
Device family
Windows 10 Insider Preview (introduced v10.0.16257.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v5)
See Also

ServerCredential 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// You can use this property in JavaScript.
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 MessageWebSocket 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<string> SupportedProtocols { get; }public IList<string> SupportedProtocols { get; }Public ReadOnly Property SupportedProtocols As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

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

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