C++ quickstart

WuKongEasySDK-CPP follows JS v2.0.4 for WebSocket JSON-RPC CONNECT, online messaging, automatic RECVACK, heartbeat, reconnect, and custom events. It uses C++17, Boost.Beast, OpenSSL, and nlohmann/json.

1. Prepare Alice and Bob

Follow Authentication & Tokens to obtain each user's uid, token, and websocketUrl from your trusted application backend. Clients connect only to Gateway and never call Product HTTP management endpoints. Wire device flags are APP 0, WEB 1, PC/Desktop 2; C++ defaults to Desktop, so the backend must store the Token under the same device category.

The default development server example uses ws://127.0.0.1:5200 with path /. Use ws://127.0.0.1:5200/ws only when your listener or proxy is configured for /ws. Across machines, use a client-reachable address; production uses wss://. Shared setup is in Run Official Examples.

2. Recommended: vcpkg + CMake

Install vcpkg and set VCPKG_ROOT to its directory. Keep Git, CMake 3.20+ and a C++17 compiler available (Visual Studio 2022 on Windows, Xcode command-line tools on macOS, GCC/Clang on Linux). The tested vcpkg revision is 04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4.

In your application directory, create vcpkg.json:

{"dependencies": ["wukong-easy-sdk"]}

vcpkg-configuration.json:

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/WuKongIM/WuKongEasySDK-CPP.git",
      "baseline": "63ec99d34c7605b64e2173d201639042e0e49de9",
      "packages": [
        "wukong-easy-sdk"
      ]
    }
  ]
}

Add the following CMakeLists.txt next to your own main.cpp:

cmake_minimum_required(VERSION 3.20)
project(my_app LANGUAGES CXX)
find_package(WuKongEasySDK 0.1 CONFIG REQUIRED)
add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE WuKongEasySDK::WuKongEasySDK)

# Linux / macOS
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2

# Windows / Visual Studio 2022
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build --config Release --parallel 2

vcpkg installs the SDK, Boost, OpenSSL and JSON automatically. The first build may compile dependencies and take several minutes; this is not a prebuilt archive. The SDK port is a static library; on Windows, distribute dependency DLLs copied beside the application when using x64-windows.

This public Git registry is maintained by WuKongIM in this repository. It is not Microsoft's curated catalog: copy the registry configuration as well as the dependency manifest. SDK source is pinned to 3e367a908f42385ab9306f9708b7456399cace7d, independently of the registry baseline. Commit both JSON files to reproduce dependency selection. Existing projects should merge these entries into their manifests instead of overwriting them.

As of 2026-09-08, the curated-catalog submission is microsoft/vcpkg#53837 and has not been merged. The proposed port builds the official v0.1.0 tag; the instructions above still use the WuKongIM custom registry and require vcpkg-configuration.json.

Independent consumer example · Registry maintenance

Alternative: download and extract a prebuilt SDK

To skip dependency compilation, download the matching ZIP and SHA256SUMS from C++ SDK v0.1.0 Release, verify its SHA-256 and extract it. You only need CMake 3.20+ and a compatible C++ development environment; no separate vcpkg installation is required.

Names start with WuKongEasySDK-CPP-0.1.0-. Each archive includes Debug/Release static SDK libraries, Boost/JSON headers, OpenSSL libraries, licenses and a minimal example. From the extracted directory:

# Linux / macOS
cmake -S example -B build -DCMAKE_TOOLCHAIN_FILE="$PWD/wukong-sdk.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

# Windows / Visual Studio 2022
cmake -S example -B build -A x64 -DCMAKE_TOOLCHAIN_FILE="$PWD/wukong-sdk.cmake"
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

wukong_example verifies initialization and destruction; wukong_chat supports interactive messaging with the Alice/Bob credentials below. For your application, retain the find_package and target_link_libraries above and point CMake's toolchain option to the extracted wukong-sdk.cmake.

OpenSSL is static on Unix and uses bundled DLLs on Windows. Deploy Windows applications with the DLLs CMake copies beside the executable and a compatible Visual C++ Redistributable. Debug runtimes are for development only. For WSS with prebuilt packages, supply a maintained CA bundle explicitly via Options::caFile (WKIM_CA_FILE in the chat example); do not depend on OpenSSL's build-machine default certificate path.

BUILD_INFO.json identifies the SDK source, registry and packaging commits; FILES.sha256.json verifies extracted content. Upgrade into a separate directory, check hashes, rebuild in a new build directory and rerun acceptance. Update the application and dependencies together and retain the previous version for rollback. Use vcpkg/source for other compilers, architectures, CRTs or dependency combinations; binary dependencies cannot be mixed arbitrarily.

Fresh jobs download each platform's ZIP and compile Debug/Release consumers at a different path, running lifecycle checks and 26 WS/WSS scenarios per configuration. Linux/macOS also use the pinned WuKongIM server to verify bidirectional messaging, reconnect and presence cleanup. Windows evidence uses the protocol fixture, not a Windows server. See prebuilt package documentation for compatibility and release acceptance.

Alternative: fetch and build pinned source

Requirements: CMake 3.20+, a C++17 compiler, Boost 1.74+, OpenSSL 1.1.1+, and nlohmann/json 3.11+. Products should use maintained dependency versions with current security fixes.

git clone https://github.com/WuKongIM/WuKongEasySDK-CPP.git
cd WuKongEasySDK-CPP
git checkout 3e367a908f42385ab9306f9708b7456399cace7d

# macOS
brew install cmake boost openssl@3 nlohmann-json
# Ubuntu / Debian
sudo apt-get install g++ cmake libboost-dev libssl-dev nlohmann-json3-dev

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

Run only the dependency command for your platform. Without an installed JSON package, CMake fetches the exact upstream 3.11.3 commit. For offline builds, preinstall dependencies and set WUKONG_FETCH_JSON=OFF.

Windows uses Visual Studio 2022 and vcpkg; the repository's vcpkg.json pins the baseline:

git -C "$env:VCPKG_ROOT" fetch origin 04a9d8e5212d01ee1dd9478eadd9caade4f8b0d4
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE="$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake" -DVCPKG_TARGET_TRIPLET=x64-windows
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failure

Add the source to your application's CMake:

add_subdirectory(external/WuKongEasySDK-CPP)
target_link_libraries(my_app PRIVATE WuKongEasySDK::WuKongEasySDK)

Alternatively, run cmake --install build --config Release --prefix /path/to/sdk-prefix, use find_package(WuKongEasySDK 0.1 CONFIG REQUIRED) downstream, and point CMAKE_PREFIX_PATH at the installation. The static-library export preserves its dependencies; Windows distribution must include any required dynamic dependencies.

3. Run the interactive example first

In two terminals, supply each user's backend-issued Token through WKIM_TOKEN, then run:

# Alice's terminal
./build/wukong_chat ws://127.0.0.1:5200 alice bob
# Bob's terminal
./build/wukong_chat ws://127.0.0.1:5200 bob alice

After both print Connected, enter text, observe Message on the other side, and send a reply. SEND completed means SENDACK succeeded. Enter /quit to disconnect and release resources. On Windows, use build/Release/wukong_chat.exe.

The example intentionally displays business message content; the SDK itself emits no logs. Do not pipe the example terminal into production log collection.

4. Connect, listen, and send in your application

This complete example reads Alice's Token from the environment, sends one message, and waits for Enter before exiting. Bob must already be online.

#include <wukong/wkim.hpp>
#include <cstdlib>
#include <iostream>

int main() {
    const char* token = std::getenv("WKIM_TOKEN");
    if (!token) return 2;
    try {
        wukong::Options options;
        options.connectionTimeout = std::chrono::seconds(10);
        options.requestTimeout = std::chrono::seconds(15);
        wukong::WKIM im("ws://127.0.0.1:5200", {"alice", token}, options);

        auto messageListener = im.on(wukong::WKIMEvent::Message,
            [](const wukong::Json& message) {
                // Copy message.at("payload") into your application's UI/event queue.
                // This callback runs on the SDK I/O thread.
                (void)message;
            });
        auto errorListener = im.on(wukong::WKIMEvent::Error,
            [](const wukong::Json&) {
                // Dispatch a sanitized failure state to the application.
            });

        im.connect().get();
        wukong::SendOptions sendOptions;
        // Supply a stable clientMsgNo when the application needs reconciliation.
        auto ack = im.send("bob", wukong::WKIMChannelType::Person,
                          {{"type", 1}, {"content", "Hello from C++!"}},
                          sendOptions).get();
        if (ack.reasonCode == 1) std::cout << "SEND completed\n";
        std::cin.get();

        im.off(messageListener);
        im.off(errorListener);
        im.disconnect().get();
        im.destroy().get();
    } catch (const wukong::Error&) {
        std::cerr << "EasySDK operation failed\n";
        return 1;
    }
}

connect() succeeds only after authentication. For group messages, use WKIMChannelType::Group after your backend creates the Channel and membership. Payload accepts a JSON object or array, encoded as Base64 UTF-8 JSON. Incoming objects, JSON text, and Base64 JSON are supported. Message IDs stay strings to preserve 64-bit precision.

Send results contain messageId, messageSeq, and reasonCode. Receive events additionally contain header, second-based timestamp, channelId, channelType, fromUid, and payload. Automatic RECVACK includes messageId and messageSeq; this is a transport receipt, not a business read receipt. See Messaging for the distinction between send completion, receipt, and application processing.

5. Own threads and account lifecycle

Each instance owns one identity and one I/O thread, with no global singleton. Public operations support concurrent application threads; events are dispatched serially on the I/O thread. A callback may enqueue an asynchronous operation, but must never wait on an SDK future. Dispatch UI updates and slow work to your application's executor.

Captured application state must outlive client shutdown. Capture the client through weak_ptr to avoid ownership cycles. Removing a listener alone does not permit freeing captured state until shutdown finishes. Socket cancellation bounds cleanup without waiting for the peer's close handshake.

6. Heartbeat, reconnect, errors, and WSS

Defaults are a 10-second total connection deadline, 15-second request deadline, 25-second ping interval, and 10-second pong timeout. A same-ID result: null acknowledges heartbeat. After a previously authenticated connection is lost, retry at most five times with exponential delay from 1 second to a 30-second cap and jitter. Initial connect failures return to the caller; authentication rejection, server-requested disconnect, malformed protocol, and manual exit stop automatic retries.

Defaults allow 1,024 pending requests, separate 4 MiB command and WebSocket write queues, and 1 MiB per wire message. Capacity failures use ErrorCode::QueueFull; local errors are negative, while server reason codes are preserved by Error::code(). A timeout or lost connection can leave send delivery unknown; reconcile through clientMsgNo. The SDK does not queue offline or automatically resend.

WSS verifies the certificate chain and hostname and requires TLS 1.2+. Use Options::caFile for a private PEM CA; the console also reads WKIM_CA_FILE. There is no certificate-verification bypass. The SDK is default-silent and never logs Tokens, payloads, URLs, raw frames, server response text, or underlying error objects.

Receive id, type, millisecond-based timestamp, and data through Event::CustomEvent; JSON-string data is parsed. Event reception depends on the server producing that notification.

Released-package three-node verification

The public v0.1.0 Linux x64 and macOS arm64 archives have also passed an independent Debug/Release consumer test against WuKongIM 5f5003778ccee6786591ed9968a5185e9213ea55: three nodes, 256 hash slots, 12 logical Slots, three Slot replicas and Token authentication enabled. C++ and the actual JS 2.0.4 SDK connect to different nodes through WSS with temporary trusted certificates. The harness checks bidirectional messaging and matching SENDACK/receive IDs, withheld-ACK timeouts, connection loss without automatic SEND replay, ingress-node crash/restart, continued traffic between surviving nodes, and online-route cleanup. See the exact inputs, receipt and repeatable test and the successful Linux/macOS workflow.

A timeout or connection error does not prove that a message was not delivered. In the fault test, the receiver already has the message while the sender cannot receive its SENDACK. Reconcile uncertain outcomes using clientMsgNo and your backend's history policy. Reconnection returns to the configured Gateway URL; it does not automatically discover a replacement URL or synchronize offline history.

This bounded test uses three processes on one host and a TLS termination proxy. It does not establish multi-host network-partition behavior, production CA configuration, Windows product-server behavior, capacity or long-duration stability.

Before production

Earlier source validation separately covers protocol and WS/WSS tests, memory and undefined-behavior instrumentation, installed consumers, and real single-node-cluster messaging, reconnect, invalid-token rejection and presence cleanup. The released-package three-node evidence above names its own artifact and server revisions; source-only results must not be attributed to a different binary.

Also validate the actual target system, real-network WSS, proxy path, Token rotation, duplicate delivery, capacity, monitoring, and rollback. This SDK does not provide offline recovery, conversations, unread counts, or push; choose a full SDK for those requirements. Return to the WuKongEasySDK overview, or continue with Release Checks.