How to use advanced WebSocket controls (HTML)
[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]
What you need to know
Enables network communications using sockets and WebSockets.
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.
- 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.
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
- 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.
Setting the options on a MessageWebSocket is done in much the same manner as in the example above.
In addition to control data, a similar set of related classes provide access to additional information on these primary classes:
- MessageWebSocketInformation - Provides socket information on a MessageWebSocket object.
- StreamWebSocketInformation - Provides socket information on a StreamWebSocket object.
These classes have properties that provide additional information on the socket.