WebSocket Protocol

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

Connection API

enum websocket::WsConnectionState

Values:

eWSCS_Ready
eWSCS_Open
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
class WebsocketConnection
#include <WebsocketConnection.h>

Subclassed by WebsocketClient

Public Functions

WebsocketConnection(HttpConnection *connection, 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 conneciton

bool bind(HttpRequest &request, HttpResponse &response)

Binds websocket connection to an http server connection.

Parameters

  • request:

  • response:

Return Value

  • bool: true on success, false otherwise

virtual void 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:

void 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

void sendString(const String &message)

Sends a string websocket message.

Parameters

  • message:

void 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.

void setUserData(void *userData)

Attaches a user data to a websocket connection.

Parameters

  • userData:

void *getUserData()

Retrieves user data attached.

Return Value

bool operator==(const WebsocketConnection &rhs) const

Test if another connection refers to the same object.

Parameters
Return Value

  • bool:

void setConnectionHandler(WebsocketDelegate handler)

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

Parameters

  • handler:

void setMessageHandler(WebsocketMessageDelegate handler)

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

Parameters

  • handler:

void setBinaryHandler(WebsocketBinaryDelegate handler)

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

Parameters

  • handler:

void setPongHandler(WebsocketDelegate handler)

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

Parameters

  • handler:

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 Value

  • bool: true on success

HttpConnection *getConnection()

Gets the underlying HTTP connection.

Return Value

  • 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 conneciton

WsConnectionState getState()

Gets the state of the websocket connection.

Return Value

  • 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 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 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 Value

  • 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

void sendPing(const String &payload = nullptr)

Send websocket ping to server.

Parameters

  • payload: Maximum 255 bytes

Return Value

  • bool: true if the data can be send, false otherwise

void sendPong(const String &payload = nullptr)

Send websocket ping to server.

Parameters

  • payload: Maximum 255 bytes

Return Value

  • bool: true if the data can be send, false otherwise

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

Set the SSL session initialisation callback.

Parameters

  • handler:

void disconnect()

Disconnects websocket client from server.