WebSocket Protocol¶
https://en.m.wikipedia.org/wiki/WebSocket
Connection API¶
-
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>
-
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 connectionisClientConnection
: 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 messagetype
:
-
void
send
(const String &message, ws_frame_type_t type = WS_FRAME_TEXT)¶ Sends websocket message from a String.
-
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 bysetUserData()
-
bool
operator==
(const WebsocketConnection &rhs) const¶ Test if another connection refers to the same object.
- Parameters
rhs
: The other WebsocketConnection to compare with
- 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 connectionisClientConnection
: 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 messagetype
:
-
void
send
(const String &message, ws_frame_type_t type = WS_FRAME_TEXT) Sends websocket message from a String.
-
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 bysetUserData()
-
bool
operator==
(const WebsocketConnection &rhs) const Test if another connection refers to the same object.
- Parameters
rhs
: The other WebsocketConnection to compare with
- 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 connectionisClientConnection
: 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&
-