sioxx API Reference#

The API is centered on sioxx::client, which owns the Engine.IO connection, and sioxx::socket, which represents one Socket.IO namespace.

Client #

Configure a client with sioxx::client_options, obtain namespace sockets with sioxx::client::socket(), and then connect to the server.

enum class sioxx::parser_kind#

Select the wire‑protocol parser used for Socket.IO packets.

json – classic text‑based protocol compatible with the reference socket.io-parser.
msgpack – binary protocol that uses MessagePack via nlohmann::json::to_msgpack/from_msgpack.

Values:

enumerator json#: Text protocol (default)

enumerator msgpack#: Binary MessagePack protocol.

struct client_options#

All tunable settings for a sioxx::client.

The struct is deliberately POD‑friendly; all members have sensible defaults.

Note

When parser_factory is provided it takes precedence over the parser enum, allowing custom parser implementations.

Public Members

parser_kind parser = {parser_kind::json}#: Which built‑in parser to use (default: json).

std::function<std::unique_ptr<parser_base>()> parser_factory#

Optional factory that creates a custom parser_base instance.

The factory must return a non‑null std::unique_ptr<parser_base>.

bool verify_tls = {true}#: Verify TLS certificates (default: true).

bool force_http_polling = {false}#

Force Engine.IO HTTP long‑polling instead of WebSocket.

Useful for environments where WebSocket upgrades are blocked.

std::vector<std::pair<std::string, std::string>> extra_headers#: Extra HTTP/WebSocket headers to send on the upgrade request.

int reconnect_attempts = {0}#: Number of retry attempts; zero disables reconnection.

std::chrono::milliseconds reconnect_delay = {2000}#: Initial back-off delay, doubled after each failed attempt.

std::chrono::milliseconds reconnect_delay_max = {30000}#: Maximum back-off delay between reconnection attempts.

double reconnect_randomization_factor = {0.5}#: Jitter factor applied to delays, in the range 0 to 1.

class client#

High‑level Socket.IO client.

Typical usage:

sioxx::client c;
c.set_open_listener([]{ std::cout << "connected\n"; });
c.connect("wss://example.com");
auto chat = c.socket("/chat");
chat->on("msg", [](const std::string&, sioxx::message data){
    std::cout << "msg: " << data.dump() << '\n';
});

Lifecycle listeners

void set_open_listener(std::function<void()> h)#: Set a callback that runs when the Engine.IO connection opens.

void set_close_listener(std::function<void(const std::string&)> h)#: Set a callback that runs when the Engine.IO connection closes.

void set_fail_listener(std::function<void()> h)#: Set a callback that runs when the Engine.IO handshake fails.

void set_error_listener(std::function<void(const std::string&)> h)#: Set a callback that runs on any error condition.

Public Functions

explicit client(client_options options = {})#

Construct a client with optional configuration.

Parameters:: options – Client options; defaults to an empty client_options.

~client()#: Destructor – cleans up the internal implementation.

void connect(const std::string &uri)#

Open a connection to the given URI.

Parameters:: uri – Full URL (e.g. wss://host:port/path).

void close()#: Close the underlying Engine.IO connection.

std::shared_ptr<sioxx::socket> socket(const std::string &nsp = "/")#

Obtain a socket for a specific namespace.

The returned socket can be used to register event listeners, emit events, and manually connect/disconnect the namespace.

Parameters:: nsp – Namespace string (default is the root namespace /).
Returns:: A shared pointer to a sioxx::socket bound to this client.

Socket #

A sioxx::socket represents a single Socket.IO namespace. It provides event listeners, event emission, acknowledgements and namespace connection lifecycle callbacks.

class socket : public std::enable_shared_from_this<socket>#

One namespace‑scoped communication channel.

The class mirrors the API of the original socket.io-client-cpp socket. Listeners are stored per‑event name; registering a listener for an existing name overwrites the previous one (consistent with the reference client).

All public methods are thread‑safe; internal state is protected by a mutex.

Event registration

void on(const std::string &event, event_listener listener)#

If a listener for the same name already exists it is replaced.

Parameters:

event – Name of the event (e.g. "message").
listener – Callable that receives the event name and its payload.

void off(const std::string &event)#: Remove the listener for a given event name.

void off_all()#: Remove all registered event listeners.

Connection lifecycle callbacks

void on_connect(connect_listener listener)#: Set a callback invoked when this namespace receives a CONNECT.

void on_disconnect(disconnect_listener listener)#: Set a callback invoked when this namespace receives a DISCONNECT.

Emission

void emit(const std::string &event, const message &data = json::array())#

Emit an event without expecting an acknowledgement.

Parameters:

event – Event name.
data – Payload (default empty JSON array). May be any JSON value.

void emit(const std::string &event, const message &data, ack_callback callback)#

Emit an event and request an acknowledgement.

Parameters:

event – Event name.
data – Payload.
callback – Function called when the server ACK arrives.

Namespace control

void connect()#: Send a CONNECT packet for this namespace.

void disconnect()#: Send a DISCONNECT packet for this namespace.

Internal callbacks – called by client_impl

void dispatch_event(const std::string &event, message data)#: Deliver an incoming event from the server.

void dispatch_ack(int id, message data)#: Deliver an incoming ACK from the server.

void mark_connected(bool connected, const std::string &disconnect_reason = "")#

Mark the socket as (dis)connected.

Called by the client implementation after a successful CONNECT or when a DISCONNECT packet is received.

Parameters:

connected – New connection state.
disconnect_reason – Optional reason string (empty if none).

Public Types

using event_listener = std::function<void(const std::string &event, message data)>#: Type of a generic event listener (receives event name & payload).

using ack_callback = std::function<void(message data)>#: Callback invoked when a server ACK arrives for an emitted event.

using connect_listener = std::function<void()>#: Listener for the connect event of this namespace.

using disconnect_listener = std::function<void(const std::string &reason)>#: Listener for the disconnect event of this namespace.

Public Functions

socket(std::weak_ptr<client_impl> client, std::string nsp)#

Construct a socket bound to a client and a namespace.

Parameters:

client – Weak reference to the owning client_impl.
nsp – Namespace string (e.g. "/chat").

inline const std::string &nsp() const#: Return the namespace this socket belongs to.

inline bool connected() const#: Whether the namespace is currently connected.

Messages #

Socket.IO values are represented directly with nlohmann::json. sioxx::json and sioxx::message are aliases for nlohmann::json, while sioxx::message_list represents an array of event arguments.

JSON‑based payload representation used throughout the library.

The original socket.io-client-cpp defined a hierarchy of sio::message types. sioxx simply aliases nlohmann::json – which already supports all required JSON primitives and binary blobs (json::binary_t).

namespace sioxx#

Typedefs

using json = nlohmann::json#: Alias for the JSON type used for every payload.

using message = json #: Alias for a single Socket.IO payload (formerly sio::message).

using message_list = json #: always a JSON array

Functions

inline message_list make_args()#

Create an empty argument list ([]).

Returns:: An empty message_list.

template<typename ...Args> inline message_list make_args(Args&&... args)#

Create a message_list from a variadic pack of values.

Each argument is converted to json via the constructor, preserving types.

Template Parameters:: Args – Types of the arguments.
Parameters:: args – Arguments to be packed.
Returns:: A JSON array containing the supplied values.

inline message binary_message(const uint8_t *data, size_t len)#

Construct a binary payload from raw memory.

The returned JSON value holds a binary_t which maps directly onto MessagePack’s bin type when using the msgpack parser.

Parameters:

data – Pointer to the first byte.
len – Number of bytes.

Returns:

A message containing the binary data.

inline message binary_message(std::vector<uint8_t> bytes)#

Construct a binary payload from a std::vector<uint8_t>.

Parameters:: bytes – Vector that will be moved into the JSON binary value.
Returns:: A message containing the binary data.

Parser extension API #

Applications can provide a custom wire-format parser by deriving from sioxx::parser_base and assigning a factory to sioxx::client_options::parser_factory.

enum class sioxx::packet_type : int#

Enumerates the different Socket.IO packet kinds.

Values match the official Socket.IO protocol specification.

Values:

enumerator connect#: Namespace connection request.

enumerator disconnect#: Namespace disconnection.

enumerator event#: Regular event with optional data.

enumerator ack#: Acknowledgement for a previous event.

enumerator connect_error#: Connection error payload.

enumerator binary_event#: Event that carries binary attachments.

enumerator binary_ack#: Ack that carries binary attachments.

struct packet#

Complete packet structure as used by parsers.

type – one of packet_type.
nsp – namespace (default “/”).
id – ACK identifier (‑1 if not used).
data – JSON payload (message).
attachments – number of binary attachments (relevant for binary packets).

Public Members

packet_type type = {packet_type::event}#: Packet type.

std::string nsp = {"/"}#: Namespace.

int id = {-1}#: ACK identifier.

json data#: Payload (JSON value)

int attachments = {0}#: Binary attachment count.

using sioxx::frame_writer = std::function<void(const std::string &payload, bool is_binary)>#: Signature of the callback that writes a fully‑encoded frame.

class parser_base#

Pure virtual base class that all parsers must derive from.

The parser receives a packet and a frame_writer. It must:

Encode a packet into one (or more) Engine.IO frames.
Decode a single Engine.IO payload back into a packet.

Note

The name() method is used for diagnostics and for selecting a parser in logs.

Public Functions

virtual ~parser_base() = default#: Virtual destructor.

virtual void encode(const packet &packet, const frame_writer &write) const = 0#

Encode a packet into an Engine.IO frame.

Parameters:

packet – Packet to encode.
write – Callback that forwards the encoded payload to the transport layer. The second argument indicates whether the frame is binary (true) or text (false).

virtual bool decode(const std::string &payload, bool is_binary, packet &out) = 0#

Decode a single Engine.IO payload.

Parameters:

payload – Raw payload received from the transport.
is_binary – true if the payload is binary, false otherwise.
out – Destination packet – filled on successful decode.

Returns:

true if the packet was completely decoded; false if more data is required (e.g., waiting for binary attachments).

virtual std::string name() const = 0#

Human‑readable name of the parser implementation.

Returns:: A string such as "json_parser" or "msgpack_parser".

sioxx API Reference#

Client#

Socket#

Messages#

Parser extension API#

Related links#

Client #

Socket #

Messages #

Parser extension API #

Related links #