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

Returns

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 *stream, ws_frame_type_t type = WS_FRAME_TEXT, bool useMask = false, bool isFin = true)

Sends websocket message from a stream.

Parameters
  • stream

  • type

  • useMask – MUST be true for client connections

  • isFin – true if this is the final frame

Returns

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.

Returns

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

Returns

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.

Returns

bool – true on success

inline HttpConnection *getConnection()

Gets the underlying HTTP connection.

Returns

HttpConnection*

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

Returns

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.

Returns

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

urlUrl address of websocket server

inline void sendPing(const String &payload = nullptr)

Send websocket ping to server.

Parameters

payload – Maximum 255 bytes

Returns

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

Returns

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