IXWebSocket

The library is organized into public interfaces for clients and servers, and private modules for low-level transport and handshake logic:

Public Interface

• IXWebSocket: The primary interface for C++ clients. It manages the receiving background thread, automatic reconnection, and simple WebSocket Pings. It has no dependencies on IX internal modules.
• IXWebSocketServer: Used to run a server. It provides a unique WebSocket object for each connection, with each connection handled in its own OS thread.

Private Modules

• IXWebSocketTransport: Handles low-level WebSocket code, framing, and raw socket management.
• IXWebSocketHandshake: Manages the connection establishment between client and server.
• Socket Handlers:
  • IXWebSocket: Handles unencrypted ws:// sockets.
  • IXWebSocketAppleSSL: Handles wss:// via AppleSSL (iOS/macOS).
  • IXWebSocketOpenSSL: Handles wss:// via OpenSSL (Android/Linux/macOS).
• IXSocketConnect: Manages connecting to the remote host.
• IXDNSLookup: Performs asynchronous DNS resolution that can be interrupted.

+-----------------------+ --- Public
|                       | Start the receiving Background thread. Auto reconnection. Simple websocket Ping.
|  IXWebSocket          | Interface used by C++ test clients. No IX dependencies.
|                       |
+-----------------------+
|                       |
|  IXWebSocketServer    | Run a server and give each connections its own WebSocket object.
|                       | Each connection is handled in a new OS thread.
|                       |
+-----------------------+ --- Private
|                       |
|  IXWebSocketTransport | Low level websocket code, framing, managing raw socket. Adapted from easywsclient.
|                       |
+-----------------------+
|                       |
|  IXWebSocketHandshake | Establish the connection between client and server.
|                       |
+-----------------------+
|                       |
|  IXWebSocket          | ws://  Unencrypted Socket handler
|  IXWebSocketAppleSSL  | wss:// TLS encrypted Socket AppleSSL handler. Used on iOS and macOS
|  IXWebSocketOpenSSL   | wss:// TLS encrypted Socket OpenSSL handler.  Used on Android and Linux
|                                                                              Can be used on macOS too.
+-----------------------+
|                       |
|  IXSocketConnect      | Connect to the remote host (client).
|                       |
+-----------------------+
|                       |
|  IXDNSLookup          | Does DNS resolution asynchronously so that it can be interrupted.
|                       |
+-----------------------+

IXWebSocket is a C++ library for WebSocket client and server development with minimal dependencies. To create a basic client:

1. Initialize the network system: On Windows, you must call ix::initNetSystem().
2. Create a ix::WebSocket object: This object manages your connection.
3. Set the URL: Use webSocket.setUrl(url) to specify the server address (e.g., wss://echo.websocket.org).
4. Set a Message Callback: Use webSocket.setOnMessageCallback() to handle incoming messages and events like Open, Close, or Error. Note that callbacks are executed in a background thread.
5. Start the connection: Call webSocket.start() to begin the background thread.
6. Send messages: Use webSocket.send(text) to transmit data to the server.

Important: Because callbacks run in a background thread, be mindful of race conditions when accessing shared data.

#include <ixwebsocket/IXNetSystem.h>
#include <ixwebsocket/IXWebSocket.h>
#include <ixwebsocket/IXUserAgent.h>
#include <iostream>

int main()
{
    // Required on Windows
    ix::initNetSystem();

    // Our websocket object
    ix::WebSocket webSocket;

    // Connect to a server with encryption
    std::string url("wss://echo.websocket.org");
    webSocket.setUrl(url);

    std::cout << "Connecting to " << url << "..." << std::endl;

    // Setup a callback to be fired (in a background thread, watch out for race conditions !)
    webSocket.setOnMessageCallback([](const ix::WebSocketMessagePtr& msg)
        {
            if (msg->type == ix::WebSocketMessageType::Message)
            {
                std::cout << "received message: " << msg->str << std::endl;
                std::cout << "> " << std::flush;
            }
            else if (msg->type == ix::WebSocketMessageType::Open)
            {
                std::cout << "Connection established" << std::endl;
                std::cout << "> " << std::flush;
            }
            else if (msg->type == ix::WebSocketMessageType::Error)
            {
                std::cout << "Connection error: " << msg->errorInfo.reason << std::endl;
                std::cout << "> " << std::flush;
            }
        }
    );

    // Start the background thread
    webSocket.start();

    // Send a message
    webSocket.send("hello world");

    std::string text;
    while (std::getline(std::cin, text))
    {
        webSocket.send(text);
        std::cout << "> " << std::flush;
    }

    return 0;
}

To update the ixwebsocket port in VCPKG, you must first obtain the latest release tag and its SHA512 checksum from the IXWebSocket releases page.

1. Download and Verify: Download the release archive (e.g., .tar.gz) and verify its integrity using openssl sha512.
2. Modify Port Files: Update the following files in your VCPKG fork:
   • ports/ixwebsocket/CONTROL: Update the Version field.
   • ports/ixwebsocket/portfile.cmake: Update the REF (the version tag) and the SHA512 hash within the vcpkg_from_github function.
3. Submit Changes: Create a new feature branch in your VCPKG fork, commit the changes, and push the branch to your origin to open a Pull Request.

# 1. Download the release
curl -s -O -L https://github.com/machinezone/IXWebSocket/archive/v9.1.9.tar.gz

# 2. Verify the checksum
openssl sha512 v9.1.9.tar.gz

# 3. Update VCPKG files (example diff)
# ports/ixwebsocket/CONTROL: Version: 9.1.9
# ports/ixwebsocket/portfile.cmake: REF v9.1.9, SHA512 <new_hash>

# 4. Git workflow for VCPKG fork
git co -b feature/ixwebsocket_9.1.9
git commit -am 'ixwebsocket: update to 9.1.9'
git push --set-upstream origin feature/ixwebsocket_9.1.9