ml::WebSocketClient Class Reference

Persistent WebSocket client with main-thread callback delivery. More...

#include <Malena/Engine/Networking/WebSocketClient.h>

Public Types
using	BinaryCallback = std::function<void(const std::vector<uint8_t>& data)>
using	CloseCallback = std::function<void(int code, const std::string& reason)>
using	ErrorCallback = std::function<void(const std::string& error)>
using	MessageCallback = std::function<void(const std::string& message)>
using	OpenCallback = std::function<void()>

Public Member Functions
	WebSocketClient ()
	WebSocketClient (const WebSocketClient &)=delete
	~WebSocketClient ()
void	connect (const std::string &url)
	Connect to url on a background thread.
void	disconnect ()
	Close the connection gracefully.
bool	isConnected () const
	Return true while the connection is open.
void	onBinary (BinaryCallback cb)
	Fired on the main thread when a binary frame arrives.
void	onClose (CloseCallback cb)
	Fired on the main thread when the connection closes.
void	onError (ErrorCallback cb)
	Fired on the main thread when a protocol or network error occurs.
void	onMessage (MessageCallback cb)
	Fired on the main thread when a UTF-8 text frame arrives.
void	onOpen (OpenCallback cb)
	Fired on the main thread when the connection opens.
WebSocketClient &	operator= (const WebSocketClient &)=delete
void	send (const nlohmann::json &json)
	Serialise json and send it as a UTF-8 text frame.
void	send (const std::string &message)
	Send a UTF-8 text frame.
void	sendBinary (const std::vector< uint8_t > &data)
	Send a binary frame.
void	setMaxReconnectAttempts (int n)
	Maximum number of reconnection attempts before giving up.
void	setReconnectDelay (int seconds)
	Set automatic reconnect delay in seconds.

Detailed Description

Persistent WebSocket client with main-thread callback delivery.

WebSocketClient maintains a single WebSocket connection on a background thread. All callbacks — onOpen, onMessage, onClose, onError — are queued and delivered on the main thread at the next frame flush, so you can safely update UI state inside them.

Basic usage

ml::WebSocketClient ws;
 
ws.onOpen([this]() {
    ws.send(R"({"type":"subscribe","channel":"questions"})");
});
 
ws.onMessage([this](const std::string& msg) {
    handleServerEvent(msg);
});
 
ws.onClose([](int code, const std::string& reason) {
    std::cout << "Closed " << code << ": " << reason << "\n";
});
 
ws.onError([](const std::string& err) {
    std::cerr << "WS error: " << err << "\n";
});
 
ws.connect("wss://api.example.com/events");

Reconnection

By default the client does not reconnect on unexpected closure. Enable automatic reconnection with a back-off delay:

ws.setReconnectDelay(2);          // try again after 2 s
ws.setMaxReconnectAttempts(5);    // give up after 5 tries (-1 = unlimited)

See also

HttpClient, NetworkManager

Definition at line 61 of file WebSocketClient.h.

Member Typedef Documentation

BinaryCallback

using ml::WebSocketClient::BinaryCallback = std::function<void(const std::vector<uint8_t>& data)>

Definition at line 65 of file WebSocketClient.h.

CloseCallback

using ml::WebSocketClient::CloseCallback = std::function<void(int code, const std::string& reason)>

Definition at line 67 of file WebSocketClient.h.

ErrorCallback

using ml::WebSocketClient::ErrorCallback = std::function<void(const std::string& error)>

Definition at line 68 of file WebSocketClient.h.

MessageCallback

using ml::WebSocketClient::MessageCallback = std::function<void(const std::string& message)>

Definition at line 64 of file WebSocketClient.h.

OpenCallback

using ml::WebSocketClient::OpenCallback = std::function<void()>

Definition at line 66 of file WebSocketClient.h.

Constructor & Destructor Documentation

WebSocketClient() [1/2]

ml::WebSocketClient::WebSocketClient

(

)

~WebSocketClient()

ml::WebSocketClient::~WebSocketClient

(

)

WebSocketClient() [2/2]

ml::WebSocketClient::WebSocketClient ( const WebSocketClient & )

delete

Member Function Documentation

connect()

void ml::WebSocketClient::connect

(

const std::string &

url

)

Connect to url on a background thread.

Supports ws:// and wss:// (TLS) schemes. Fires onOpen when the handshake completes.

Parameters

url	WebSocket URL, e.g. "wss://api.example.com/events".

disconnect()

void ml::WebSocketClient::disconnect

(

)

Close the connection gracefully.

Fires onClose with code 1000 (normal closure). Safe to call when already disconnected.

isConnected()

bool ml::WebSocketClient::isConnected ( ) const

nodiscard

Return true while the connection is open.

onBinary()

void ml::WebSocketClient::onBinary

(

BinaryCallback

cb

)

Fired on the main thread when a binary frame arrives.

Parameters

cb	Callback receiving the binary payload.

onClose()

void ml::WebSocketClient::onClose

(

CloseCallback

cb

)

Fired on the main thread when the connection closes.

Parameters

cb	Callback receiving the WebSocket close code and reason.

onError()

void ml::WebSocketClient::onError

(

ErrorCallback

cb

)

Fired on the main thread when a protocol or network error occurs.

Parameters

cb	Callback receiving an error description.

onMessage()

void ml::WebSocketClient::onMessage

(

MessageCallback

cb

)

Fired on the main thread when a UTF-8 text frame arrives.

Parameters

cb	Callback receiving the text payload.

onOpen()

void ml::WebSocketClient::onOpen

(

OpenCallback

cb

)

Fired on the main thread when the connection opens.

Use this to send an initial subscription message.

operator=()

WebSocketClient & ml::WebSocketClient::operator= ( const WebSocketClient & )

delete

send() [1/2]

void ml::WebSocketClient::send ( const nlohmann::json & json )

inline

Serialise json and send it as a UTF-8 text frame.

Equivalent to calling send(json.dump()).

ws.send({{"type", "subscribe"}, {"channel", "questions"}});
ws.send({{"type", "answer"}, {"questionId", 7}, {"value", "RAII"}});

Definition at line 123 of file WebSocketClient.h.

send() [2/2]

void ml::WebSocketClient::send

(

const std::string &

message

)

Send a UTF-8 text frame.

Parameters

message

Text payload.

sendBinary()

void ml::WebSocketClient::sendBinary

(

const std::vector< uint8_t > &

data

)

Send a binary frame.

Parameters

data	Binary payload.

setMaxReconnectAttempts()

void ml::WebSocketClient::setMaxReconnectAttempts

(

int

n

)

Maximum number of reconnection attempts before giving up.

Parameters

n	Pass -1 for unlimited attempts.

setReconnectDelay()

void ml::WebSocketClient::setReconnectDelay

(

int

seconds

)

Set automatic reconnect delay in seconds.

When non-zero, the client reconnects after an unexpected closure. The delay doubles on each failed attempt up to maxReconnectAttempts.

Parameters

seconds

Delay before the first reconnect attempt. 0 = disabled.

---

The documentation for this class was generated from the following file:

• Engine/Networking/WebSocketClient.h