Stream​Web​Socket Stream​Web​Socket Stream​Web​Socket Class

Definition

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

public : sealed class StreamWebSocket : IClosable, IStreamWebSocket, IStreamWebSocket2, IWebSocketpublic sealed class StreamWebSocket : IDisposable, IStreamWebSocket, IStreamWebSocket2, IWebSocketPublic NotInheritable Class StreamWebSocket Implements IDisposable, IStreamWebSocket, IStreamWebSocket2, IWebSocket
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()

Creates a new StreamWebSocket object.

public : StreamWebSocket()public StreamWebSocket()Public Sub New()
Attributes

Properties

Control Control Control

Gets socket control data on a StreamWebSocket object.

public : StreamWebSocketControl Control { get; }public StreamWebSocketControl Control { get; }Public ReadOnly Property Control As StreamWebSocketControl
Attributes

Remarks

The Control property gets the StreamWebSocketControl instance associated with a StreamWebSocket object.

A StreamWebSocketControl object is automatically created with the parent StreamWebSocket object. The StreamWebSocketControl instance can then be used to get or set control data used by the StreamWebSocket object. These properties on the MessageWebSocketControl instance include the following:

Any changes to the StreamWebSocketControl property values must be set before the StreamWebSocket is connected. As a result if you need to make changes to the NoDelay, OutboundBufferSizeInBytes, ProxyCredential, ServerCredential, or SupportedProtocols properties, then these changes must occur before a successful call to the ConnectAsync method on the StreamWebSocket.

See Also

Information Information Information

Gets socket information on a StreamWebSocket object.

public : StreamWebSocketInformation Information { get; }public StreamWebSocketInformation Information { get; }Public ReadOnly Property Information As StreamWebSocketInformation
Attributes

InputStream InputStream InputStream

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

public : IInputStream InputStream { get; }public IInputStream InputStream { get; }Public ReadOnly Property InputStream As IInputStream
Value
IInputStream IInputStream IInputStream

A sequential stream of bytes to be read from the remote destination.

Attributes

Remarks

This property is used with the DataReader object to read incoming data received from the remote network destination on a socket object.

See Also

OutputStream OutputStream OutputStream

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

public : IOutputStream OutputStream { get; }public IOutputStream OutputStream { get; }Public ReadOnly Property OutputStream As IOutputStream
Value
IOutputStream IOutputStream IOutputStream

A sequential stream of bytes to be written to the remote destination.

Attributes

Remarks

This property is used with the DataWriter object to write outgoing data to be sent to the remote network destination on a StreamWebSocket object.

The following specific errors can occur when you call IOutputStream.FlushAsync on the OutputStream of a StreamWebSocket if the websocket is in an invalid state at the time.

  • If the websocket instance has been explicitly closed (via delete, Dispose, or Close) or implicitly closed (fallen out of scope), FlushAsync throws an RO_E_CLOSED exception.
  • If the IOutputStream object associated with the websocket has been explicitly closed (via delete, Dispose, or Close) or implicitly closed (for example, by disposing of a DataWriter instance before calling DetachStream on it), FlushAsync throws an RO_E_CLOSED exception.
  • If the websocket is not connected yet (ConnectAsync has not been called), then FlushAsync throws an E_ILLEGAL_METHOD_CALL exception.
See Also

Methods

Close() Close() Close()

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

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net
Attributes

Remarks

The Close method is used by Windows app using JavaScript. For apps written using the .NET Framework 4.5 in C# and VB.NET, the Close method is exposed as the method on the StreamWebSocket. For apps written in C++, the Close method will be called when using the delete keyword on the object.

See Also

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

Closes the StreamWebSocket and indicates a reason for the closure.

public : void Close(unsigned short code, PlatForm::String reason)This member is not implemented in C#This member is not implemented in VB.Net
Parameters
code
System.UInt16 System.UInt16 System.UInt16

Status code indicating the reason for closure.

reason
System.String System.String System.String

Optional UTF-8-encoded data with additional information about the closure.

Attributes
See Also

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

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

public : IAsyncAction ConnectAsync(Uri uri)public IAsyncAction ConnectAsync(Uri uri)Public Function ConnectAsync(uri As Uri) As IAsyncAction
Parameters
uri
Uri Uri Uri

An absolute Uri for the server to connect to.

Returns

An asynchronous connect operation on a StreamWebSocket object.

Attributes

Remarks

The ConnectAsync method initiates the WebSocket handshake with a remote network destination, and then negotiates the subprotocol.

For WebSocket connections over TCP, use the ws:// scheme in the uri. For secure WebSocket connections over TLS/SSL, use the wss:// scheme.

See Also

Dispose() Dispose() Dispose()

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

This member is not implemented in C++void Dispose()Sub Dispose
Attributes

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.

public : void SetRequestHeader(PlatForm::String headerName, PlatForm::String headerValue)public void SetRequestHeader(String headerName, String headerValue)Public Function SetRequestHeader(headerName As String, headerValue As String) As void
Parameters
headerName
System.String System.String System.String

The name of the request header.

headerValue
System.String System.String System.String

The value of the request header.

Attributes

Remarks

The SetRequestHeader method must be called prior to calling the ConnectAsync method. Calling the SetRequestHeader method after calling the ConnectAsync method will result in an error.

Using the SetRequestHeader method to add a Sec-WebSocket-Extensions header is not supported.

See Also

Events

Closed Closed Closed

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

public : event TypedEventHandler Closedpublic event TypedEventHandler ClosedPublic Event Closed
Attributes

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.

public : event TypedEventHandler ServerCustomValidationRequestedpublic event TypedEventHandler ServerCustomValidationRequestedPublic Event ServerCustomValidationRequested
Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)
Capabilities
privateNetworkClientServer internetClient

Remarks

Note that this event is raised after the default OS validation has been performed successfully, and that the default OS validation includes taking the IgnorableServerCertificateErrors control option into account.

Use the WebSocketServerCustomValidationRequestedEventArgs properties to access the server certificate and intermediate certificates being offered for validation.

In order to ensure proper completion, if your custom validation process involves any async operations, be sure to use the WebSocketServerCustomValidationRequestedEventArgs.GetDeferral method to get a deferral object that your event handler holds for the duration of the validation operation. When your validation is complete, you must call Deferral.Complete whether you accept or reject validation.

As an example of the kind of validation you can do in this event handler: you could compare the server certificate to a locally stored trusted certificate that matches the expected server certificate. In your event handler, you would compare the SHA-256 hash of the local certificate to the hash of the server certificate. If the hash values match, then the certificates are assumed to match, and server validation should succeed. If the hash values don't match, then the certificates don't match and validation should fail.

To indicate validation failure, call the WebSocketServerCustomValidationRequestedEventArgs.Reject method. To indicate validation success, simply return from the event handler.

Note that whether validation succeeds or fails, you must call Deferral.Complete on the deferral object you acquired when you started the validation process.

See Also