Unosquare
    Show / Hide Table of Contents

    Class WebSocketModule

    A base class for modules that handle WebSocket connections.

    Inheritance
    Object
    WebModuleBase
    WebSocketModule
    Implements
    IWebModuleImpl
    IWebModule
    IDisposable
    Inherited Members
    WebModuleBase.Container
    WebModuleBase.IWebModuleImpl.SetContainer(IWebModuleContainer)
    WebModuleBase.BaseRoute
    WebModuleBase.OnUnhandledException
    WebModuleBase.OnHttpException
    WebModuleBase.LogSource
    WebModuleBase.Start(CancellationToken)
    WebModuleBase.MatchUrlPath(String)
    WebModuleBase.HandleRequestAsync(IHttpContext)
    WebModuleBase.SetContainer(IWebModuleContainer)
    Namespace: EmbedIO.WebSockets
    Syntax
    public abstract class WebSocketModule : WebModuleBase, IWebModuleImpl, IWebModule, IDisposable
    Remarks

    Each WebSocket server has a list of WebSocket subprotocols it can accept.

    When a client initiates a WebSocket opening handshake:

    • if the list of accepted subprotocols is empty, the connection is accepted only if no SecWebSocketProtocol header is present in the request;
    • if the list of accepted subprotocols is not empty, the connection is accepted only if one or more SecWebSocketProtocol headers are present in the request and one of them specifies one of the subprotocols in the list. The first subprotocol specified by the client that is also present in the module's list is then specified in the handshake response.
    If a connection is not accepted because of a subprotocol mismatch, a 400 Bad Request response is sent back to the client. The response contains one or more SecWebSocketProtocol headers that specify the list of accepted subprotocols (if any).

    Constructors

    WebSocketModule(String, Boolean)

    Initializes a new instance of the WebSocketModule class.

    Declaration
    protected WebSocketModule(string path, bool enableConnectionWatchdog)
    Parameters
    Type Name Description
    String path

    The URL path of the WebSocket endpoint to serve.

    Boolean enableConnectionWatchdog

    If set to true, contexts representing closed connections will automatically be purged from ActiveContexts every 30 seconds..

    Properties

    ActiveContexts

    Gets a list of IWebSocketContext interfaces representing the currently connected clients.

    Declaration
    protected IReadOnlyList<IWebSocketContext> ActiveContexts { get; }
    Property Value
    Type Description
    IReadOnlyList<IWebSocketContext>

    Encoding

    Gets the Encoding used by the SendAsync(IWebSocketContext, String) method to send a string. The default is UTF8 per the WebSocket specification.

    Declaration
    protected Encoding Encoding { get; set; }
    Property Value
    Type Description
    Encoding

    IsFinalHandler

    Gets a value indicating whether processing of a request should stop after a module has handled it.

    Declaration
    public override sealed bool IsFinalHandler { get; }
    Property Value
    Type Description
    Boolean
    Overrides
    WebModuleBase.IsFinalHandler
    Remarks

    If this property is true, a HTTP context's SetHandled() method will be automatically called immediately after after the returned by HandleRequestAsync(IHttpContext) is completed. This will prevent the context from being passed further along to other modules.

    See Also
    IsHandled
    SetHandled()

    KeepAliveInterval

    Gets or sets the keep-alive interval for the WebSocket connection. The default is 30 seconds.

    Declaration
    protected TimeSpan KeepAliveInterval { get; set; }
    Property Value
    Type Description
    TimeSpan

    MaxMessageSize

    Gets or sets the maximum size of a received message. If a message exceeding the maximum size is received from a client, the connection is closed automatically.

    The default value is 0, which disables message size checking.

    Declaration
    protected int MaxMessageSize { get; set; }
    Property Value
    Type Description
    Int32

    Methods

    AddProtocol(String)

    Adds a WebSocket subprotocol to the list of protocols supported by a WebSocketModule.

    Declaration
    protected void AddProtocol(string protocol)
    Parameters
    Type Name Description
    String protocol

    The protocol name to add to the list.

    See Also
    AddProtocols(IEnumerable<String>)
    AddProtocols(String[])

    AddProtocols(IEnumerable<String>)

    Adds one or more WebSocket subprotocols to the list of protocols supported by a WebSocketModule.

    Declaration
    protected void AddProtocols(IEnumerable<string> protocols)
    Parameters
    Type Name Description
    IEnumerable<String> protocols

    The protocol names to add to the list.

    Remarks

    This method enumerates protocols just once; hence, if an exception is thrown because one of the specified protocols is null or contains invalid characters, any preceding protocol is added to the list of supported protocols.

    See Also
    AddProtocol(String)
    AddProtocols(String[])

    AddProtocols(String[])

    Adds one or more WebSocket subprotocols to the list of protocols supported by a WebSocketModule.

    Declaration
    protected void AddProtocols(params string[] protocols)
    Parameters
    Type Name Description
    String[] protocols

    The protocol names to add to the list.

    Remarks

    This method performs validation checks on all specified protocols before adding them to the list of supported protocols; hence, if an exception is thrown because one of the specified protocols is null or contains invalid characters, none of the specified protocol names are added to the list.

    See Also
    AddProtocol(String)
    AddProtocols(IEnumerable<String>)

    BroadcastAsync(Byte[])

    Broadcasts the specified payload to all connected WebSocket clients.

    Declaration
    protected Task BroadcastAsync(byte[] payload)
    Parameters
    Type Name Description
    Byte[] payload

    The payload.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    BroadcastAsync(Byte[], Func<IWebSocketContext, Boolean>)

    Broadcasts the specified payload to selected WebSocket clients.

    Declaration
    protected Task BroadcastAsync(byte[] payload, Func<IWebSocketContext, bool> selector)
    Parameters
    Type Name Description
    Byte[] payload

    The payload.

    Func<IWebSocketContext, Boolean> selector

    A callback function that must return true for each context to be included in the broadcast.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    BroadcastAsync(String)

    Broadcasts the specified payload to all connected WebSocket clients.

    Declaration
    protected Task BroadcastAsync(string payload)
    Parameters
    Type Name Description
    String payload

    The payload.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    BroadcastAsync(String, Func<IWebSocketContext, Boolean>)

    Broadcasts the specified payload to selected WebSocket clients.

    Declaration
    protected Task BroadcastAsync(string payload, Func<IWebSocketContext, bool> selector)
    Parameters
    Type Name Description
    String payload

    The payload.

    Func<IWebSocketContext, Boolean> selector

    A callback function that must return true for each context to be included in the broadcast.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    CloseAsync(IWebSocketContext)

    Closes the specified web socket, removes it and disposes it.

    Declaration
    protected Task CloseAsync(IWebSocketContext context)
    Parameters
    Type Name Description
    IWebSocketContext context

    The web socket.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    Dispose()

    Declaration
    public void Dispose()

    Dispose(Boolean)

    Releases unmanaged and - optionally - managed resources.

    Declaration
    protected virtual void Dispose(bool disposing)
    Parameters
    Type Name Description
    Boolean disposing

    true to release both managed and unmanaged resources; false to release only unmanaged resources.

    OnClientConnectedAsync(IWebSocketContext)

    Called when this WebSocket server accepts a new client.

    Declaration
    protected virtual Task OnClientConnectedAsync(IWebSocketContext context)
    Parameters
    Type Name Description
    IWebSocketContext context

    The context.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    OnClientDisconnectedAsync(IWebSocketContext)

    Called when the server has removed a connected client for any reason.

    Declaration
    protected virtual Task OnClientDisconnectedAsync(IWebSocketContext context)
    Parameters
    Type Name Description
    IWebSocketContext context

    The context.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    OnFrameReceivedAsync(IWebSocketContext, Byte[], IWebSocketReceiveResult)

    Called when this WebSocket server receives a message frame regardless if the frame represents the EndOfMessage.

    Declaration
    protected virtual Task OnFrameReceivedAsync(IWebSocketContext context, byte[] buffer, IWebSocketReceiveResult result)
    Parameters
    Type Name Description
    IWebSocketContext context

    The context.

    Byte[] buffer

    The buffer.

    IWebSocketReceiveResult result

    The result.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    OnMessageReceivedAsync(IWebSocketContext, Byte[], IWebSocketReceiveResult)

    Called when this WebSocket server receives a full message (EndOfMessage) from a client.

    Declaration
    protected abstract Task OnMessageReceivedAsync(IWebSocketContext context, byte[] buffer, IWebSocketReceiveResult result)
    Parameters
    Type Name Description
    IWebSocketContext context

    The context.

    Byte[] buffer

    The buffer.

    IWebSocketReceiveResult result

    The result.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    OnRequestAsync(IHttpContext)

    Called to handle a request from a client.

    Declaration
    protected override sealed Task OnRequestAsync(IHttpContext context)
    Parameters
    Type Name Description
    IHttpContext context

    The context of the request being handled.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    Overrides
    WebModuleBase.OnRequestAsync(IHttpContext)

    OnStart(CancellationToken)

    Called when a module is started, immediately before locking the module's configuration.

    Declaration
    protected override void OnStart(CancellationToken cancellationToken)
    Parameters
    Type Name Description
    CancellationToken cancellationToken

    A used to stop the web server.

    Overrides
    WebModuleBase.OnStart(CancellationToken)

    SendAsync(IWebSocketContext, Byte[])

    Sends a binary payload.

    Declaration
    protected static Task SendAsync(IWebSocketContext context, byte[] payload)
    Parameters
    Type Name Description
    IWebSocketContext context

    The web socket.

    Byte[] payload

    The payload.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    SendAsync(IWebSocketContext, String)

    Sends a text payload.

    Declaration
    protected static Task SendAsync(IWebSocketContext context, string payload)
    Parameters
    Type Name Description
    IWebSocketContext context

    The web socket.

    String payload

    The payload.

    Returns
    Type Description
    Task

    A representing the ongoing operation.

    Implements

    IWebModuleImpl
    IWebModule
    IDisposable

    Comments

    Back to top Copyright © 2017-2019 Unosquare