How to use advanced WebSocket controls (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This topic explains how to use advanced socket controls when using the MessageWebSocket and StreamWebSocket features in a Windows Runtime app.

What you need to know

Technologies

Windows.Networking.Sockets

Enables network communications using sockets and WebSockets.

Prerequisites

The examples in this topic are provided in JavaScript. A basic understanding of WebSockets is recommended.

Overview of advanced WebSocket controls

The MessageWebSocket and StreamWebSocket classes follow the same model for using advanced controls. Corresponding with each of the above primary classes are related classes to access advanced controls:

MessageWebSocketControl - Provides socket control of the quality of service on a MessageWebSocket object.
StreamWebSocketControl - Provides socket control data on a StreamWebSocket object.

The basic model to use advanced controls is the same for both types of WebSockets. The discussion below uses StreamWebSocket as an example, but the same process can be used with a MessageWebSocket.

Create a StreamWebSocket.
Use the StreamWebSocket.Control property to get the StreamWebSocketControl instance associated with a StreamWebSocket object.
Set a property on the StreamWebSocketControl to set an advanced socket option.

The app must always set the property on the StreamWebSocketControl before issuing a connect operation. Because of this, it is best to set any advanced options immediately after the socket is created. Do not try and set a StreamWebSocketControl property after a socket has called the ConnectAsync method.

Advanced StreamWebSocket controls

There are several advanced options on the StreamWebSocket.

StreamWebSocketControl.NoDelay - Indicates whether the Nagle algorithm is used on a StreamWebSocket object.
StreamWebSocketControl.OutboundBufferSizeInBytes - Controls the size, in bytes, of the send buffer to be used for sending data on a StreamWebSocket object.
StreamWebSocketControl.ProxyCredential - Provides the credential to use to authenticate to the proxy server through HTTP header authentication using a StreamWebSocket object.
StreamWebSocketControl.ServerCredential - Provides the credential to use to authenticate to the WebSocket server through HTTP header authentication using a StreamWebSocket object.
StreamWebSocketControl.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.

As an example, let's look at the StreamWebSocketControl.NoDelay option in more detail. The default setting when a StreamWebSocket is created is for this option to be set to true, which disables the Nagle algorithm. However, if the StreamWebSocket will be used for an app that sends many small packets, and latency is not an issue, then the Nagle algorithm could be enabled by setting StreamWebSocketControl.NoDelay to false in order to reduce network traffic.

The following example creates a StreamWebSocket and sets the StreamWebSocketControl.NoDelay to false. Once 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 isn't disabled
    clientWebSocket.control.noDelay = false;
   
    // Now you can call the ConnectAsync method to connect the StreamWebSocket.

Advanced MessageWebSocket controls

Many of the advanced options on the MessageWebSocket are the same as those on the StreamWebSocket, but there are some differences.

MessageWebSocketControl.MaxMessageSize - Controls the maximum message size, in bytes, for a WebSocket message to be configured on the MessageWebSocket object.
MessageWebSocketControl.MessageType - Controls the WebSocket message type (binary or UTF-8) to be configured on a MessageWebSocket object.
MessageWebSocketControl.OutboundBufferSizeInBytes - Controls the size, in bytes, of the send buffer to be used for sending data on a MessageWebSocket object.
MessageWebSocketControl.ProxyCredential - Provides the credential to use to authenticate to the proxy server through HTTP header authentication using a MessageWebSocket object.
MessageWebSocketControl.ServerCredential - Provides the credential to use to authenticate to the WebSocket server through HTTP header authentication using a MessageWebSocket object.
MessageWebSocketControl.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.