API.md

API Manual

Installation

The library requires the Boost Beast and Jsoncpp libraries to handle WebSocket communications and JSON data manipulation respectively. Install these dependencies using CMake if they are not already present on your system.

Required Libraries

• Boost Beast (version >= 1.76.0): Used for WebSocket implementation. Available at boost.org.
• Jsoncpp: Used for JSON parsing and serialization. Known for its performance and ease of use in C++ environments.

Examples

Two simple examples are provided demonstrating the Library in a simple raw C and a C++ classed implementation. Compile the examples using:

- mkdir build && cd build
- cmake ..
- make
- ./example_client_simple or ./example_client_classed

Classes

Connection

The Connection class manages WebSocket connections using Boost Beast. It handles asynchronous read, write, and connection management activities necessary for real-time communication.

Constructor

• Connection(net::io_context& ioc): Initializes a new connection with a given I/O context. This context is used to handle all I/O operations for the WebSocket.

Methods

• std::thread launch_socket(const char *host, const char *port): Starts the WebSocket connection on a separate thread.
• void stop(): Stops the WebSocket connection and cleans up resources.
• void subscribe(std::string channel, socketCallback callback): Subscribes to a specific channel with a callback to handle incoming messages.
• void unsubscribe(std::string channel): Unsubscribes from a specific channel.
• void publish(std::string channel, std::string data): Publishes data to a specific channel.
• void message_processing(): Handles the internal message processing in its thread.

Callbacks

• socketCallback: A function type that handles incoming messages. Takes an event as std::string and data as Json::Value.

Members

• websocket::stream<beast::tcp_stream> ws_: WebSocket stream for the connection.
• beast::flat_buffer buffer_: Buffer used for reading WebSocket messages.

SocketClusterClient

The SocketClusterClient class manages multiple WebSocket connections and provides methods to create and retrieve these connections.

Constructor

• SocketClusterClient(): Initializes a new client capable of handling WebSocket connections.

Methods

• std::shared_ptr<Connection> createConnection(const char *url, const char *port): Creates and returns a new connection to the specified URL and port.
• std::list<std::shared_ptr<Connection>>& getConnections(): Returns a list of all active connections.

Members

• std::list<std::shared_ptr<Connection>> m_connections: List storing all managed connections.

Errors & Exceptions

• 1000 - Normal Closure : Connection closed successfully.
• 1001 - Going Away : Server or client is shutting down.
• 1002 - Protocol Error : Protocol violation detected.
• 1003 - Unsupported Data : The endpoint received data of a type it cannot accept.
• 1006 - Abnormal Closure : Connection closed abnormally without a status code.

Example Usage of SocketClusterClient Library

This example demonstrates how to use the SocketClusterClient and Connection classes to connect to a WebSocket server, subscribe to a channel, and handle incoming messages.

#include <iostream>
#include "SocketClusterClient.h"

// Define a callback function to handle messages received on the WebSocket
void handleMessage(std::string event, Json::Value data) {
    std::cout << "Event: " << event << "\nMessage received: " << data.toStyledString() << std::endl;
}

int main() {
    // Create a client instance
    SocketClusterClient client;

    // Create a new WebSocket connection to the desired host and port
    auto connection = client.createConnection("ws://example.com", "80");

    // Subscribe to a channel with the defined callback
    connection->subscribe("exampleChannel", handleMessage);
    
    // Publish to a channel
    connection->publish("exampleChannel", "Hello World!");

    return 0;
}