StreamWebSocket StreamWebSocket StreamWebSocket StreamWebSocket StreamWebSocket Class

Definition

Supports network communication that allows reading and writing streams using a WebSocket.

public : sealed class StreamWebSocket : IClosable, IStreamWebSocket, IStreamWebSocket2, IWebSocket
struct winrt::Windows::Networking::Sockets::StreamWebSocket : IClosable, IStreamWebSocket, IStreamWebSocket2, IWebSocket
public sealed class StreamWebSocket : IDisposable, IStreamWebSocket, IStreamWebSocket2, IWebSocket
Public NotInheritable Class StreamWebSocket Implements IDisposable, IStreamWebSocket, IStreamWebSocket2, IWebSocket
var streamWebSocket = new streamWebSocket();
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
privateNetworkClientServer internetClient

Remarks

The StreamWebSocket class provides a stream-based abstraction of the message-based WebSocket protocol. This is useful for scenarios in which large files (such as photos or movies) need to be transferred. Using StreamWebSocket allows sections of a message to be read with each read operation, rather than requiring the entire message to be read in a single operation (as with MessageWebSocket ).

StreamWebSocket only supports binary messages. For UTF-8 messages, MessageWebSocket must be used.

Handling exceptions

You must write code to handle exceptions when you call asynchronous methods on the StreamWebSocket class. Exceptions can result from parameter validation errors, name resolutions failures, and network errors. Exceptions from network errors (loss of connectivity, connection failures, and HTTP server failures, for example) can happen at any time. These errors result in exceptions being thrown. If not handled by your app, an exception can cause your entire app to be terminated by the runtime.

The Windows.Networking.Sockets namespace has a convenient helper method and enumeration for handling errors when using WebSockets. This can be useful for handling specific network exceptions differently in your app. An app can also use the HRESULT from the exception on parameter validation errors to learn more detailed information on the error that caused the exception.

For more information on possible exceptions and how to handle exceptions, see Handling exceptions in network apps.

Using StreamWebSocket on Windows Server 2012

On Windows Server 2012 and Windows Server 2012 R2, the Windows.Networking.dll that implements most of the classes in the Windows.Networking.Sockets namespace will fail to load unless the Media Foundation feature is enabled. As a result, apps that use StreamWebSocket and related WebSocket classes in the Windows.Networking.Sockets namespace will fail if the Media Foundation feature is disabled. Windows Server 2012 or Windows Server 2012 R2 installs with the Media Foundation feature disabled.

The Media Foundation feature can be enabled on Windows Server 2012 or Windows Server 2012 R2 using Server Manager or by entering the following text in a command prompt or a script:

dism /online /enable-feature /featurename:ServerMediaFoundationAfter the Media Foundation feature is enabled, the user is prompted to restart. Once the computer is restarted, classes for sockets and WebSockets in the Windows.Networking.Sockets namespace will work as expected.

Constructors

StreamWebSocket() StreamWebSocket() StreamWebSocket() StreamWebSocket() StreamWebSocket()

Creates a new StreamWebSocket object.

Properties

Control Control Control Control Control

Gets socket control data on a StreamWebSocket object.

Information Information Information Information Information

Gets socket information on a StreamWebSocket object.

InputStream InputStream InputStream InputStream InputStream

Gets the input stream to read from the remote destination on a StreamWebSocket object.

OutputStream OutputStream OutputStream OutputStream OutputStream

Gets the output stream to write to the remote network destination on a StreamWebSocket object.

Methods

Close() Close() Close() Close() Close()

Closes the StreamWebSocket and sends an empty close frame to the server.

Close(UInt16, String) Close(UInt16, String) Close(UInt16, String) Close(UInt16, String) Close(UInt16, String)

Closes the StreamWebSocket and indicates a reason for the closure.

ConnectAsync(Uri) ConnectAsync(Uri) ConnectAsync(Uri) ConnectAsync(Uri) ConnectAsync(Uri)

Starts an asynchronous operation to connect to a remote network destination on a StreamWebSocket object.

Dispose() Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

SetRequestHeader(String, String) SetRequestHeader(String, String) SetRequestHeader(String, String) SetRequestHeader(String, String) SetRequestHeader(String, String)

Adds an HTTP request header to the HTTP request message used in the WebSocket protocol handshake by the StreamWebSocket object.

Events

Closed Closed Closed Closed Closed

Occurs when a close frame is received on the StreamWebSocket object as part of the close handshake.

ServerCustomValidationRequested ServerCustomValidationRequested ServerCustomValidationRequested ServerCustomValidationRequested ServerCustomValidationRequested

Occurs when a new StreamWebSocket connection to a secured server URI (wss: protocol) is being validated. Handle this event if you want to implement custom server validation for the connection.

See Also