WebSocket Protocol

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

Connection API

enum websocket::WsConnectionState

Values:

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

Public Functions

WsFrameInfo()
WsFrameInfo(ws_frame_type_t type, char *payload, size_t payloadLength)

Public Members

ws_frame_type_t type = WS_FRAME_TEXT
char *payload = nullptr
size_t payloadLength = 0
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

virtual ~WebsocketConnection()
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
  • void*: The user data previously set by setUserData()

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

WebsocketClient()
WebsocketClient(HttpConnection *connection)
HttpConnection *getHttpConnection()
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.

Protected Functions

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
  • void*: The user data previously set by setUserData()

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

Protected 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&