WebSocket Protocol

https://en.m.wikipedia.org/wiki/WebSocket

Connection API

enum WsConnectionState

Current state of Websocket connection.

Values:

enumerator eWSCS_Ready
enumerator eWSCS_Open
enumerator eWSCS_Closed
using WebsocketList = Vector<WebsocketConnection*>
using WebsocketDelegate = Delegate<void(WebsocketConnection&)>
using WebsocketMessageDelegate = Delegate<void(WebsocketConnection&, const String&)>
using WebsocketBinaryDelegate = Delegate<void(WebsocketConnection&, uint8_t *data, size_t size)>
WEBSOCKET_VERSION
struct WsFrameInfo
#include <WebsocketConnection.h>
class WebsocketConnection
#include <WebsocketConnection.h>

Subclassed by WebsocketClient

Public Functions

WebsocketConnection(HttpConnection *connection = nullptr, bool isClientConnection = true)

Constructs a websocket connection on top of http client or server connection.

Parameters:

  • connection – the transport connection

  • isClientConnection – true when the passed connection is an http client connection

bool bind(HttpRequest &request, HttpResponse &response)

Binds websocket connection to an http server connection.

Parameters:

  • request –

  • response –

Return values:

bool – true on success, false otherwise

bool send(const char *message, size_t length, ws_frame_type_t type = WS_FRAME_TEXT)

Sends a websocket message from a buffer.

Parameters:

  • message –

  • length – Quantity of data in message

  • type –

inline bool send(const String &message, ws_frame_type_t type = WS_FRAME_TEXT)

Sends websocket message from a String.

Note

A String may contain arbitrary data, not just text, so can use this for any frame type

Parameters:
bool send(IDataSourceStream *source, ws_frame_type_t type = WS_FRAME_TEXT, bool useMask = false, bool isFin = true)

Sends websocket message from a stream.

Parameters:

  • source – The stream to send - we get ownership of the stream

  • type –

  • useMask – MUST be true for client connections

  • isFin – true if this is the final frame

Return values:

bool – true on success

inline bool sendString(const String &message)

Sends a string websocket message.

Parameters:

message –

inline bool sendBinary(const uint8_t *data, size_t length)

Sends a binary websocket message.

Parameters:

  • data –

  • length –

void close()

Closes a websocket connection (without closing the underlying http connection)

void reset()

Resets a websocket connection.

inline void setUserData(void *userData)

Attaches a user data to a websocket connection.

Parameters:

userData –

inline void *getUserData()

Retrieves user data attached.

Return values:

void* – The user data previously set by setUserData()

inline bool operator==(const WebsocketConnection &rhs) const

Test if another connection refers to the same object.

Parameters:

rhs – The other WebsocketConnection to compare with

Return values:

bool –

inline void setConnectionHandler(WebsocketDelegate handler)

Sets the callback handler to be called after successful websocket connection.

Parameters:

handler –

inline void setMessageHandler(WebsocketMessageDelegate handler)

Sets the callback handler to be called after a websocket message is received.

Parameters:

handler –

inline void setBinaryHandler(WebsocketBinaryDelegate handler)

Sets the callback handler to be called after a binary websocket message is received.

Parameters:

handler –

inline void setPongHandler(WebsocketDelegate handler)

Sets the callback handler to be called when pong reply received.

Parameters:

handler –

inline void setDisconnectionHandler(WebsocketDelegate handler)

Sets the callback handler to be called before closing a websocket connection.

Parameters:

handler –

void activate()

Should be called after a websocket connection is established to activate the websocket parser and allow sending of websocket data.

bool onConnected()

Call this method when the websocket connection was (re)activated.

Return values:

bool – true on success

inline HttpConnection *getConnection()

Gets the underlying HTTP connection.

Return values:

HttpConnection* –

void setConnection(HttpConnection *connection, bool isClientConnection = true)

Sets the underlying (transport ) HTTP connection.

Parameters:

  • connection – the transport connection

  • isClientConnection – true when the passed connection is an http client connection

inline WsConnectionState getState()

Gets the state of the websocket connection.

Return values:

WsConnectionState –

Public Static Functions

static void broadcast(const char *message, size_t length, ws_frame_type_t type = WS_FRAME_TEXT)

Broadcasts a message to all active websocket connections.

Parameters:

  • message –

  • length –

  • type –

static inline void broadcast(const String &message, ws_frame_type_t type = WS_FRAME_TEXT)

Broadcasts a message to all active websocket connections.

Parameters:

  • message –

  • type –

static inline const WebsocketList &getActiveWebsockets()

Obtain the list of active websockets.

Note

Return value is const as only restricted operations should be carried out on the list.

Return values:

const – WebsocketList&

Client API

class WebsocketClient : protected WebsocketConnection
#include <WebsocketClient.h>

Websocket Client.

Public Functions

bool connect(const Url &url)

Connects websocket client to server.

Parameters:

url – Url address of websocket server

inline void sendPing(const String &payload = nullptr)

Send websocket ping to server.

Parameters:

payload – Maximum 255 bytes

Return values:

bool – true if the data can be send, false otherwise

inline void sendPong(const String &payload = nullptr)

Send websocket ping to server.

Parameters:

payload – Maximum 255 bytes

Return values:

bool – true if the data can be send, false otherwise

inline void setSslInitHandler(Ssl::Session::InitDelegate handler)

Set the SSL session initialisation callback.

Parameters:

handler –

inline void setBinaryHandler(WebsocketBinaryDelegate handler)

Sets the callback handler to be called after a binary websocket message is received.

Parameters:

handler –

inline void setConnectionHandler(WebsocketDelegate handler)

Sets the callback handler to be called after successful websocket connection.

Parameters:

handler –

inline void setDisconnectionHandler(WebsocketDelegate handler)

Sets the callback handler to be called before closing a websocket connection.

Parameters:

handler –

inline void setMessageHandler(WebsocketMessageDelegate handler)

Sets the callback handler to be called after a websocket message is received.

Parameters:

handler –

bool send(const char *message, size_t length, ws_frame_type_t type = WS_FRAME_TEXT)

Sends a websocket message from a buffer.

Parameters:

  • message –

  • length – Quantity of data in message

  • type –

inline bool send(const String &message, ws_frame_type_t type = WS_FRAME_TEXT)

Sends websocket message from a String.

Note

A String may contain arbitrary data, not just text, so can use this for any frame type

Parameters:
bool send(IDataSourceStream *source, ws_frame_type_t type = WS_FRAME_TEXT, bool useMask = false, bool isFin = true)

Sends websocket message from a stream.

Parameters:

  • source – The stream to send - we get ownership of the stream

  • type –

  • useMask – MUST be true for client connections

  • isFin – true if this is the final frame

Return values:

bool – true on success

inline bool sendBinary(const uint8_t *data, size_t length)

Sends a binary websocket message.

Parameters:

  • data –

  • length –

inline bool sendString(const String &message)

Sends a string websocket message.

Parameters:

message –

void close()

Closes a websocket connection (without closing the underlying http connection)

inline WsConnectionState getState()

Gets the state of the websocket connection.

Return values:

WsConnectionState –