Client guide

C++ and desktop development guide

Use the shared native SDK on Linux and embedded targets, then reuse the same service and model design in desktop wrappers.

The C++ SDK is the shared native foundation for Linux, embedded, mobile wrappers, and supported desktop packaging. BMXClient owns the service objects and implements network callbacks; services expose synchronous operations while listeners deliver asynchronous state changes.

Object model

Native SDK relationshipstext

>BMXClient
>|----BMXNetworkListener
>|----BMXChatService
>    |----BMXChatServiceListener
>    |----BMXConversation
>    |----BMXMessage
>|----BMXUserService
>    |----BMXUserServiceListener
>    |----BMXUserProfile
>|----BMXRosterService
>    |----BMXRosterServiceListener
>    |----BMXRosterItem
>|----BMXGroupService
>    |----BMXGroupServiceListener
>    |----BMXGroup

Component	Responsibility
BMXClient	Configuration, service ownership, authentication entry points, and network events.
BMXChatService	Conversations, history, send operations, receipts, recalls, and attachments.
BMXUserService	Registration, sign-in/out, profile, and user settings.
BMXRosterService	Contacts, applications, aliases, and block lists.
BMXGroupService	Group lifecycle, membership, roles, policy, announcements, and shared files.

Link and package the SDK

Use the headers and libraries from one matching SDK release.
Link zlib, OpenSSL crypto, libcurl, and other platform libraries listed by that release.
The embedded demo additionally uses ncurses; application SDK use does not imply a terminal UI dependency.
Select the correct x86, x86_64, ARM, or MIPS package and match its compiler ABI and C++ runtime.
Keep SDK calls and listener lifetimes behind an application-owned native client layer when integrating with Electron or another UI runtime.

Initialise and own BMXClient

Create the clientcpp

#include "bmx_client.h"
config = BMXSDKConfigPtr(new BMXSDKConfig(BMXClientType::Linux, "", path, path, "3.0", "1234", "userAgent"));
config->setAppID("welovemaxim");
config->setDBCryptoKey("testkey");
config->setDeviceUuid("b81f412e-fcb2-44fb-9f44-5e8e5b1e809e");
config->setConsoleOutput(false);
config->setLogLevel(BMXLogLevel::Debug);
client = BMXClient::create(config);

Replace sample App IDs, paths, device UUIDs, and database keys with deployment-owned values.
Create one client per signed-in application context and make its lifetime longer than all registered listeners.
Use stable writable data and cache paths and protect them from concurrent clients.
Disable debug/console logging or redirect it through the product's redaction policy in release builds.

BMXUserProfilePtr profile;
BMXErrorCode errorCode = client->signUpNewUser("maximtest1", "123456", "1", profile);
if (BMXErrorCode::NoError == errorCode) {
  std::cout << "signUpNewUser successs!" << std::endl;
} else {
  std::cout << "signUpNewUser failure!" << std::endl;
  std::cout << getErrorMessage(errorCode) << std::endl;
}

Password and fast sign-incpp

BMXErrorCode errorCode = client->signInByName("maximtest1", "1");
if (BMXErrorCode::NoError == errorCode) {
  std::cout << "signInByName successs!" << std::endl;
} else {
  std::cout << "signInByName failure!" << std::endl;
  std::cout << getErrorMessage(errorCode) << std::endl;
}

// 快速登录,不需要获取token
BMXErrorCode errorCode = client->fastSignInByName("maximtest1", "1");
if (BMXErrorCode::NoError == errorCode) {
  std::cout << "signInByName successs!" << std::endl;
} else {
  std::cout << "signInByName failure!" << std::endl;
  std::cout << getErrorMessage(errorCode) << std::endl;
}

Keep server access tokens out of distributed native binaries. If your deployment uses user-token sign-in, obtain a user-scoped token from your backend over your authenticated application channel.

Conversations and contacts

Read conversationscpp

BMXConversationList list = client->getChatService().getAllConversations();

Read the contact listcpp

std::vector<int64_t> list;
BMXErrorCode errorCode = client->getRosterService().get(list, true);
if (list.size() > 0) {
  cout << list[0] << endl;
}

BMXRosterService also applies, accepts, declines, and removes relationships and manages the block list. Use listener events to update caches and UI adapters; force a network refresh only when required.

Groups and permissions

BMXGroupService owns creation, search, destruction, join/leave, invitations, applications, members, owner/admin roles, mute and block lists, announcements, shared files, and group policy. Treat every operation as permissioned and use the returned BMXErrorCode instead of assuming the local role is still current.

State to cache	Refresh trigger
Group profile and policy	Group update listener or explicit refresh.
Member roles and nicknames	Member-added, removed, role, or nickname events.
Invitations and applications	Corresponding group-service listener callbacks.
Mute/block status	Administrative event or permission failure.

Build text and attachment messages

Text messagecpp

/**
  * @param from 消息发送者Id
  * @param to 消息接收者Id
  * @param type 消息类型
  * @param conversationId 会话id
  * @param content 消息内容
  **/
  BMXMessagePtr msg = BMXMessage::createMessage(2272061685216, 2272061881760, (BMXMessage::MessageType)1, 2272061881760, "test");

Image attachmentcpp

/**
  * @param path 本地路径
  * @param size 图片的大小，宽度和高度
  * @param displayName 展示名
  **/
BMXImageAttachmentPtr attachment(new BMXImageAttachment(path, size, displayName));
BMXMessagePtr msg = BMXMessage::createMessage(2272061685216, 2272061881760, (BMXMessage::MessageType)1, 2272061881760, attachment);

Content	Native attachment
Image	BMXImageAttachment
File	BMXFileAttachment
Location	BMXLocationAttachment
Voice	BMXVoiceAttachment
Video	BMXVideoAttachment
Custom	Extension/config data supported by the SDK version

Send and observe messages

Message operationscpp

client->getChatService().sendMessage(msg);

Listener lifecyclecpp

client->getChatService().addChatListener(listener); //添加聊天监听者
client->getChatService().removeChatListener(listener);  //移除聊天监听者

Implement onReceive for incoming messages and onStatusChanged for outgoing state.
Implement upload and attachment status callbacks before supporting media messages.
Use createForwardMessage before forwarding, and resend only a failed message.
Recall within the server window and make callback processing idempotent.
Remove listeners before destroying their target objects or the client.

Desktop and embedded integration

Target	Integration boundary
Linux native	Link the C++ SDK directly and marshal callbacks into the application event loop.
Embedded	Select the correct CPU package, constrain cache/storage, and make reconnect plus upload policy explicit.
Electron desktop	Expose a narrow native bridge; keep BMX objects in native code and pass serializable application models to the renderer.
Other desktop UI	Own BMXClient in a long-lived application service and dispatch callbacks onto the UI framework thread.

Native release checklist

Verify compiler, standard library, architecture, and crypto/network library compatibility.
Test database and cache paths across upgrade, crash, low-disk, and multiple-process scenarios.
Test reconnect and authentication recovery after DNS, network, and server changes.
Use smart pointers consistently and make listener ownership explicit.
Redact credentials, tokens, message text, and file URLs from release logs.

C++ & desktop SDK reference →