MessageWebSocketControl MessageWebSocketControl MessageWebSocketControl MessageWebSocketControl Class

Provides socket control data on a MessageWebSocket.

Syntax

Declaration

public sealed class MessageWebSocketControlpublic sealed class MessageWebSocketControlPublic NotInheritable Class MessageWebSocketControlpublic sealed class MessageWebSocketControl

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 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(Uri) method on the MessageWebSocket.

The following example creates a MessageWebSocket, and then demonstrates how to set the 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 summary

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.

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

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

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

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

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

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.

Properties

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

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

    Remarks

    Examples

    The following example demonstrates how to ignore the ChainValidationResult 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(Uri) 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(Uri) 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 uint MaxMessageSize { get; set; }public uint MaxMessageSize { get; set; }Public ReadWrite Property MaxMessageSize As uintpublic uint MaxMessageSize { get; set; }

    Property Value

    • uint
      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(Uri) method on the MessageWebSocket object. If the MessageWebSocket is already connected, an attempt to set this property will return an error.

  • 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 SocketMessageTypepublic SocketMessageType MessageType { get; set; }

    Property Value

    Remarks

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

    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

  • OutboundBufferSizeInBytes
    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 uintpublic uint OutboundBufferSizeInBytes { get; set; }

    Property Value

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

  • 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 PasswordCredentialpublic PasswordCredential ProxyCredential { get; set; }

    Property Value

    Remarks

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

  • 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 PasswordCredentialpublic PasswordCredential ServerCredential { get; set; }

    Property Value

    Remarks

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

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

    Property Value

    • 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(Uri) 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(Uri) method will not result in an error but the new value is ignored. However, if the ConnectAsync(Uri) 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(Uri) method call and the new value will be applied.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.DualApiPartitionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.Networking.Sockets.dll