Linux C++

The Signaling SDK API reference is divided into the following sections:

• Setup
• User authentication
• Channels
• Topics
• Messages
• Presence
• Storage
• Lock
• Enumerated types
• Troubleshooting

Setup

The API reference for the Signaling SDK documents interface descriptions, methods, basic usage, and return values of the Signaling APIs.

RtmConfig

Description

Use the RtmConfig to set additional properties for Signaling initialization. These configuration properties will take effect throughout the lifecycle of the Signaling client and affect the behavior of the Signaling client.

Method

You can create RtmConfig instances as follows:

RtmConfig config;
config.appId = "your_appid";
config.userId = "your_name";
config.eventHandler = new RtmHandler();
config.areaCode = RTM_AREA_CODE_CN | RTM_AREA_CODE_AS;
config.protocolType = RTM_PROTOCOL_TYPE_TCP_UDP;
config.presenceTimeout = 300;
config.heartbeatInterval = 5;
config.reconnectTimeout = 60;
config.useStringUserId = true;
config.ispPolicyEnabled = false;
config.proxyConfig = proxyConfig;
config.logConfig = logConfig;
config.encryptionConfig = encryptionConfig;
config.privateConfig = privateConfig;

RtmLogConfig

Use the RtmLogConfig instance to configure and store local log files named agora.log. During the debugging phase, you can greatly improve efficiency by storing and tracking the running status of the app through logs. If you encounter complex problems and need Agora technical support to assist with the investigation, you need to provide the log information. RtmLogConfig contains the following properties:

RtmProxyConfig

Use the RtmProxyConfig instance to set properties related to the client Proxy service. In some restricted network environments, you might need to use this feature.

RtmProxyConfig contains the following properties:

RtmEncryptionConfig

Use the RtmEncryptionConfig instance to set the properties required for the client-side encryption. After successfully setting encryption modes, encryption keys, and other related properties, the SDK automatically encrypts and decrypts all messages sent or all statuses set by the user on the client side.

RtmEncryptionConfig contains the following properties:

RtmPrivateConfig

Use the RtmPrivateConfig instance to set the properties required for the private deployment.

RtmPrivateConfig contains the following properties:

Basic usage

RtmConfig config;
config.appId = "your_appid";
config.userId = "your_name";
config.eventHandler = new RtmHandler();

config.logConfig.level = RTM_LOG_LEVEL_INFO;
config.logConfig.filePath = "your_path";
config.logConfig.fileSizeInKB = 10 * 1024;

config.proxyConfig.proxyType = RTM_PROXY_TYPE_HTTP;
config.proxyConfig.server = "your_server_address"; // your server address
config.proxyConfig.port = 8080;
config.proxyConfig.account = "your_user_account";
config.proxyConfig.password = "your_password";

uint8_t salt[32] = {1,2,3,4,5};
config.encryptionConfig.encryptionKey = "your_key";
config.encryptionConfig.encryptionMode = RTM_ENCRYPTION_MODE_AES_256_GCM;
memcpy(config.encryptionConfig.encryptionSalt, salt, 32);

std::vector<const char*> hosts;
hosts.push_back("xxx");
config.privateConfig.accessPointHosts = hosts.data();
config.privateConfig.accessPointHostsCount = hosts.size();
config.privateConfig.serviceType = RTM_SERVICE_TYPE_MESSAGE | RTM_SERVICE_TYPE_STREAM;

createAgoraRtmClient

Description

Call the createAgoraRtmClient method to create and initialize the Signaling Client instance.

Method

You can create an instance as follows:

AGORA_API IRtmClient* AGORA_CALL createAgoraRtmClient(const RtmConfig& config, int& errorCode);

Basic usage

RtmConfig config;
config.appId = "your_appid"
config.userId = "your_name";
config.eventHandler = eventHandler_.get();
int errorCode = 0;
rtmClient_ = createAgoraRtmClient(config, errorCode);
if (!rtmClient_ || errorCode != 0) {
    std::cout << RED <<"error creating rtm service!" << std::endl;
    exit(0);
}

Return value

• If the method call succeeds, the SDK creates a Signaling client instance for subsequent calls to other Signaling APIs.

• If the method call fails, the SDK returns NULL.

Event Listeners

Description

Signaling has a total of 8 types of event notifications, as shown in the following table:

Add event listeners

Add an event listener object as follows:

 // only need override the event which you want to receive
class RtmEventHandler: public IRtmEventHandler {
    void onMessageEvent(const MessageEvent &event) {}
    void onTopicEvent(const TopicEvent &event) {}
    void onConnectionStateChanged(const char *channelName, RTM_CONNECTION_STATE state, RTM_CONNECTION_CHANGE_REASON reason) {}
    void onLoginResult(RTM_ERROR_CODE errorCode) {}
    void onStorageEvent(const StorageEvent &event) {}
    void onLockEvent(const LockEvent &event) {}
    void onLinkStateEvent(const LinkStateEvent& event) {}
    ...
};

RtmConfig config;
config.eventHandler = new RtmEventHandler();

MessageEvent

Message event.

MessageEvent contains the following properties:

PresenceEvent

User presence event.

PresenceEvent contains the following properties:

IntervalInfo contains the following properties:

SnapshotInfo contains the following properties:

UserList contains the following properties:

UserState contains the following properties:

StateItem data type contains the following properties:

TopicEvent

Topic event.

TopicEvent contains the following properties:

TopicInfo data type contains the following properties:

PublisherInfo data type contains the following properties:

StorageEvent

Storage event.

StorageEvent contains the following properties:

LockEvent

Lock event.

LockEvent contains the following properties:

The LockDetail data type contains the following properties:

LinkStateEvent

SDK link state event.

LinkStateEvent data type contains the following properties:

login

Description

After creating and initializing the Signaling instance, you need to perform the login operation to log in to the Signaling service. After successful login, the client establishes a long connection with the Signaling server, and then the SDK allows the client to access Signaling resources.

Method

You can log in to the Signaling system as follows:

virtual void login(const char* token, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onLoginResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
uint64_t requestId;
rtmClient->login("your_token", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onLoginResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) {
        if (errorCode != RTM_ERROR_OK) {
            printf("login rtm failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("login rtm success\n");
        }
    }
};

logout

Description

When you no longer need to operate, you can log out of the system. This operation affects the PCU item in your billing data.

Method

You can log out as follows:

virtual void logout(uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onLogoutResult callback and return the API execution result through the following parameters:

Basic usage

uint64_t requestId;
rtmClient->logout(requestId);

 // Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onLogoutResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) {
        if (errorCode != RTM_ERROR_OK) {
            printf("logout rtm failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("logout rtm success\n");
        }
    }
};

Synchronous return value

• 0: Success.
• < 0: Failure.

releaseLock

Description

Once you no longer need the Signaling service, it is best to destroy the IRtmClient instance. Doing so protects you from the performance degradation caused by memory leaks, errors, and exceptions.

Method

You can destroy the IRtmClient instance as follows:

virtual int release() = 0;

Basic usage

rtmClient->release();

Return value

• 0: Success.
• < 0: Failure.

User authentication

Authentication is the process of validating the identity of each user before they access a system. Agora uses digital tokens to authenticate users and their privileges.

Signaling provides 3 types of channels: message channels, user channels and stream channels. Different types of channels require different types of tokens:

• For message channels and user channels: When logging in to the Signaling system using the login method, you only need to pass the token that enables Signaling service.
• For stream channels: In addition to the Signaling token, when joining a stream channel using the joinTopic method, you also need to pass the token that enables RTC service.

The token is valid for up to 24 hours. Agora recommends that you update the token before it expires. This article describes how to update the token.

For more information on generating and using tokens, see Secure authentication with tokens.

IRtmClient::renewToken

Description

Call the IRtmClient::renewToken method to renew the Signaling token.

To ensure timely token updates, Agora recommends listening for the onTokenPrivilegeWillExpire callback. See Event listeners for details. Once you successfully add the event listener, when the Signaling token is about to expire within 30 seconds, the SDK triggers the onTokenPrivilegeWillExpire callback to notify the user about the impending token expiration.

Upon receiving this callback, you can generate a new Signaling token on the server-side and call the renewToken method to provide the SDK with the newly generated Signaling token.

Method

You can call the IRtmClient::renewToken method as follows:

virtual void renewToken(const char* token, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onRenewTokenResult callback and return the API execution result through the following parameters:

Basic usage

rtmClient->renewToken("your token");

IStreamChannel::renewToken

Description

Call the IStreamChannel::renewToken method to renew the RTC token.

To ensure timely token updates, Agora recommends listening for the onTokenPrivilegeWillExpire callback. See Event listeners for details. Once you successfully add the event listener, when the RTC token is about to expire within 30 seconds, the SDK triggers the onTokenPrivilegeWillExpire callback to notify the user about the impending token expiration.

Upon receiving this callback, you can generate a new RTC token on the server-side and call the renewToken method to provide the SDK with the newly generated RTC token.

Method

You can call the IStreamChannel::renewToken method as follows:

virtual void renewToken(const char* token, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onRenewTokenResult callback and return the API execution result through the following parameters:

Basic usage

uint64_t requestId;
streamChannel->renewToken("your token", requestId);

Channels

Signaling provides a highly efficient channel management mechanism for data transmission. Any user who subscribes or joins a channel can receive messages and events transmitted within 100 milliseconds. Signaling allows clients to subscribe to hundreds or even thousands of channels. Most Signaling APIs perform actions such as sending, receiving, and encrypting based on channels.

Based on capabilities of Agora, Signaling channels are divided into two types to match different application use-cases:

• Message Channel: Follows the industry-standard Pub/Sub (publish/subscribe) mode. You can send and receive messages within the channel by subscribing to a channel, and do not need to create the channel in advance. There is no limit to the number of publishers and subscribers in a channel.
• Stream Channel: Follows a concept similar to the observer pattern in the industry, where users need to create and join a channel before sending and receiving messages. You can create different topics in the channel, and messages are organized and managed through topics.

IRtmClient Signaling client instance

subscribeTopic

Description

Signaling provides event notification capabilities for messages and states. By listening for callbacks, you can receive messages and events within subscribed channels. For information on how to add and set event listeners, see Event Listeners.

By calling the subscribeTopic method, the client can subscribe to a message channel and start receiving messages and event notifications within the channel. After successfully calling this method, users who subscribe to the channel and enable the presence event listener can receive a RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL type of the onPresenceEvent event. See Event Listeners.

Method

You can call the subscribeTopic method as follows:

virtual void subscribe(const char* channelName, const SubscribeOptions& options, uint64_t& requestId) = 0;

SubscribeOptions contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onSubscribeResult callback and return the API execution result through the following parameters:

Basic usage

 // Method call
SubscribeOptions options;
options.withLock = true;
options.withMessage = true;
options.withMetadata = true;
options.withPresence = true;
options.beQuiet = false;

uint64_t requestId;
rtmClient->subscribe("channelName", options, requestId);

 // Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onSubscribeResult(const uint64_t requestId, const char *channelName, RTM_ERROR_CODE errorCode) {
        if (errorCode != RTM_ERROR_OK) {
            printf("subscribe rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("subscribe rtm channel %s success\n", channelName);
        }
    }
};

unsubscribeTopic

Description

If you no longer need to subscribe to a channel, you can call the unsubscribeTopic method to unsubscribe from the channel. After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL type of the onPresenceEvent event notification. See Event Listeners.

Method

You can call the unsubscribeTopic method as follows:

virtual void unsubscribe(const char* channelName, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onUnsubscribeResult callback and return the API execution result through the following parameters:

Basic usage

 // Method call
uint64_t requestId;
rtm_client->unsubscribe("channelName", requestId);

 // Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onUnsubscribeResult(const uint64_t requestId, const char* channelName, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("unsubscribe rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("unsubscribe rtm channel %s success\n", channelName);
        }
    }
};

createAgoraRtmClient

Description

Before using a stream channel, you need to call the createAgoraRtmClient method to create the IStreamChannel instance. After successfully creating the instance, you can call its relevant methods to implement functions, such as joining the channel, leaving the channel, sending messages in a topic, and subscribing to messages in a topic.

Method

You can call the createAgoraRtmClient method as follows:

virtual IStreamChannel* createStreamChannel(const char* channelName, int& errorCode) = 0;

Basic usage

int errorCode = 0;
IStreamChannel* streamChannel = rtmClient->createStreamChannel("channelName", errorCode);
if (streamChannel == nullptr || errorCode != 0) {
    printf("create stream channel failed");
} else {
    printf("create stream channel success");
}

Return value

• Success: Returns an instance of IStreamChannel to use for subsequent calls to other stream channel APIs.
• Failure: Returns NULL.

IStreamChannel Stream channel instance

joinTopic

Description

After successfully creating a stream channel, you can call the joinTopic method to join the stream channel.

Once you join the channel, you can implement channel-related functions. At this point, users who subscribe to the channel and add event listeners can receive the following event notifications:

• For the local user:
  • The RTM_PRESENCE_EVENT_TYPE_SNAPSHOT type of the onPresenceEvent event.
  • The RTM_TOPIC_EVENT_TYPE_SNAPSHOT type of the onTopicEvent event.
• For remote users: The RTM_PRESENCE_EVENT_TYPE_REMOTE_JOIN_CHANNEL type of the onPresenceEvent event.

Method

You can call the joinTopic method as follows:

virtual void join(const JoinChannelOptions& options, uint64_t& requestId) = 0;

The JoinChannelOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onJoinResult callback and return the API execution result through the following parameters:

Basic usage

 // Method call
JoinChannelOptions options;
options.token = "your_token";
options.withLock = false;
options.withMetadata = false;
options.withPresence = true;
options.beQuiet = false;
uint64_t requestId;
streamChannel->join(options, requestId);

 // Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onJoinResult(const uint64_t requestId, const char *channelName, const char *userId, RTM_ERROR_CODE errorCode) {
        if (errorCode != RTM_ERROR_OK) {
            printf("join rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("join rtm channel %s success\n", channelName);
        }
    }
};

leaveTopic

Description

If you no longer need to stay in a channel, you can call the leaveTopic method to leave the channel. After leaving the channel, you can no longer receive any messages, states, or event notifications from this channel. At the same time, you can no loger be the topic publisher or subscriber of all topics. If you want to restore your previous publisher role and subscribing relationship, you need to call joinTopic, joinTopic and subscribeTopic methods in order.

After successfully leaving the channel, remote users in the channel can receive the RTM_PRESENCE_EVENT_TYPE_REMOTE_LEAVE_CHANNEL type of the onPresenceEvent event notification. For details, see Event Listeners.

Method

You can call the leaveTopic method as follows:

virtual void leave(uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onLeaveResult callback and return the API execution result through the following parameters:

Basic usage

 // Method call
uint64_t requestId;
streamChannel->leave(requestId);

 // Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onLeaveResult(const uint64_t requestId, const char *channelName, const char *userId, RTM_ERROR_CODE errorCode) {
        if (errorCode != RTM_ERROR_OK) {
           printf("leave rtm channel failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("leave rtm channel %s success\n", channelName);
        }
    }
};

releaseLock

Description

If you no longer need a channel, you can call the releaseLock method to destroy the corresponding stream channel instance and release resources. Calling the releaseLock method does not destroy the stream channel, and it can be re-joined later by calling createAgoraRtmClient and joinTopic again.

Method

You can call the releaseLock method as follows:

virtual int release() = 0;

Basic usage

int ret = streamChannel->release();

Return value

• 0: Success.
• < 0: Failure.

Topics

Topic is a data stream management mechanism in stream channels. Users can use topics to subscribe to and distribute data streams, as well as notify events in data streams in stream channels.

IStreamChannel Stream channel instance

joinTopic

Description

The purpose of joining a topic is to register as one of the message publishers for the topic, so that the user can send messages in the topic. This operation does not affect whether or not the user becomes a subscriber to the topic.

After successfully joining a topic, users who subscribe to that topic and add event listeners can receive the RTM_TOPIC_EVENT_TYPE_REMOTE_JOIN_TOPIC type of the onTopicEvent event notification. For details, see Event Listeners.

Method

You can call the joinTopic method as follows:

virtual void joinTopic(const char* topic, const JoinTopicOptions& options, uint64_t& requestId) = 0;

The JoinTopicOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onJoinTopicResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
JoinTopicOptions options;
options.qos = RTM_MESSAGE_QOS_ORDERED;

uint64_t requestId;
stream_channel->joinTopic("topicName", options, requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onJoinTopicResult(const uint64_t requestId, const char *channelName, const char *userId, const char *topic, const char *meta, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("JoinTopic failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("JoinTopic success\n");
        }
    }
};

publishTopicMessage

Description

Use the publishTopicMessage method to send messages to a topic. Users who have subscribed to the topic and the message publisher in the channel can receive the message within 100 milliseconds. Before calling the publishTopicMessage method, users need to join the stream channel, and then register as a message publisher for that topic by calling the joinTopic method.

The messages sent by users are encrypted with TLS during transmission, and data link encryption is enabled by default and cannot be disabled. To achieve a higher level of data security, users can also enable client encryption during initialization. For details, see Setup.

Method

You can call the publishTopicMessage[1/2] and publishTopicMessage[2/2] method as follows:

virtual void publishTopicMessage(const char* topic, const char* message, size_t length, const TopicMessageOptions& option, uint64_t& requestId) = 0;

The TopicMessageOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onPublishTopicMessageResult callback and return the API execution result through the following parameters:

Basic usage

Example 1: Send string messages to a specified channel.

std::string message = "hello world";
TopicMessageOptions options;
options.messageType = RTM_MESSAGE_TYPE_STRING;
options.customType = "Text";

uint64_t requestId;
streamChannel->publishTopicMessage("topicName", message.c_str(), message.size(), options, requestId);

Example 2: Send byte messages to a specified channel.

TopicMessageOptions options;
options.messageType = RTM_MESSAGE_TYPE_BINARY;
options.customType = "ByteArray";

char message[5] = {0x00, 0x01, 0x02, 0x03, 0x04};

uint64_t requestId;
stream_channel->publishTopicMessage("topic_name", message, 5, options, requestId);

leaveTopic

Description

When you no longer need to publish messages to a topic, to release resources, you can call the leaveTopic method to unregister as a message publisher for that topic. This method does not affect whether or not you subscribe to that topic or any other operations performed by other users on that topic.

After successfully calling this method, users who subscribe to the channel and enable event listeners can receive the RTM_TOPIC_EVENT_TYPE_REMOTE_LEAVE_TOPIC type of the onTopicEvent event notification. See Event Listeners.

Method

You can call the leaveTopic method as follows:

virtual void leaveTopic(const char* topic, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onLeaveTopicResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
uint64_t requestId;
streamChannel->leaveTopic("topicName", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onLeaveTopicResult(const uint64_t requestId, const char *channelName, const char *userId, const char *topic, const char *meta, RTM_ERROR_CODE errorCode) override
    {
        if (errorCode != RTM_ERROR_OK) {
            printf("LeaveTopic failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("LeaveTopic success\n");
        }
    }
};

subscribeTopic

Description

After joining the channel, you can call the subscribeTopic method to subscribe to the message publisher of the topic in the channel.

subscribeTopic is an incremental method. For example, if you call this method for the first time with a subscribing list of [UserA, UserB], and then call it again with a subscribing list of [UserB, UserC], the final successful subscribing result is [UserA, UserB, UserC].

A user can subscribe to a maximum of 50 topics in each channel, and a maximum of 64 message publishers in each topic.

Method

You can call the subscribeTopic method as follows:

virtual void subscribeTopic(const char* topic, const TopicOptions& options, uint64_t& requestId) = 0;

The TopicOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onSubscribeTopicResult callback and return the API execution result through the following parameters:

The UserList data type contains the following properties:

Basic usage

Example 1: Subscribe to the specified message publisher in the topic.

std::vector<const char*> users;
users.push_back("UserA");
users.push_back("UserB");

TopicOptions options;
options.users = users.data();
options.userCount = users.size();

uint64_t requestId;
streamChannel->subscribeTopic("topicName", options, requestId);

Example 2: Randomly subscribe to 64 message publishers in the topic.

TopicOptions options;

uint64_t requestId;
streamChannel->subscribeTopic("topicName", options, requestId);

Example 3: Asynchronous callback.

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onSubscribeTopicResult(const uint64_t requestId, const char *channelName, const char *userId, const char *topic, UserList succeedUsers, UserList failedUsers, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("SubscribeTopic failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("SubscribeTopic success\n");
        }
    }
};

unsubscribeTopic

Description

If you are no longer interested in a specified topic, or no longer need to subscribe to one or more message publishers in the topic, you can call the unsubscribeTopic method to unsubscribe from the topic or the specified message publishers in the topic.

Method

You can call the unsubscribeTopic method as follows:

virtual void unsubscribeTopic(const char* topic, const TopicOptions& options, uint64_t& requestId) = 0;

The TopicOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onUnsubscribeTopicResult callback and return the API execution result through the following parameters:

Basic usage

Example 1: Unsubscribe the specified message publisher in the topic

std::vector<const char*> users;
users.push_back("UserA");
users.push_back("UserB");

TopicOptions options;
options.users = users.data();
options.userCount = users.size();

uint64_t requestId;
streamChannel->unsubscribeTopic("topicName", options, requestId);

Example 2: Randomly unsubscribe 64 message publishers from the topic.

TopicOptions options;

uint64_t requestId;
streamChannel->unsubscribeTopic("topicName", options, requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onUnsubscribeTopicResult(const uint64_t requestId, const char* channelName, const char* topic, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("UnsubscribeTopic failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("UnsubscribeTopic success\n");
        }
    }
};

Synchronous return value

• 0: Success.
• < 0: Failure.

getSubscribedUserList

Description

If you need to get the list of publishers that you subscribe to in a specific topic, you can call the getSubscribedUserList method.

Method

You can call the getSubscribedUserList method as follows:

virtual void getSubscribedUserList(const char* topic, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onGetSubscribedUserListResult callback and return the API execution result through the following parameters:

The UserList data type contains the following properties:

Basic usage

// Method call
uint64_t requestId;
streamChannel->getSubscribedUserList("topic", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onGetSubscribedUserListResult(const uint64_t requestId, const char* channelName, const char* topic, UserList users, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("getSubscribedUserList failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("getSubscribedUserList success\n");
            for (int i = 0 ;i < users.userCount; i++) {
                printf("user: %s\n", users.users[i]);
            }
        }
    }
};

Messages

Sending and receiving messages is the most basic function of the Signaling service. Any message sent by the Signaling server can be delivered to any online subscribing user within 100 ms. Depending on your business requirements, you can send messages to one user only or broadcast messages to multiple users.

Signaling offers 3 types of channels: message channels, user channels, and stream channels. These channel types have the following differences in how messages are transmitted and methods are called:

• Message Channel: The real-time channel. Messages are transmitted through the channel, and the channel is highly scalable. Local users can call the publishTopicMessage method, set the channelType parameter to RTM_CHANNEL_TYPE_MESSAGE, and set the channelName parameter to the channel name to send messages in the channel. The remote users can call the subscribeTopic method to subscribe to the channel and receive messages.
• User Channel: The real-time channel. Messages are transmitted to the specified user. Local users can call the publishTopicMessage method, set the channelType parameter to RTM_CHANNEL_TYPE_USER, and set the channelName parameter to the user ID to send messages to the specified user. The specified remote users receive messages through the onMessageEvent event notifications.
• Stream Channel: The streaming transmission channel. Messages are transmitted through the topic. Users need to join a channel first, and then join a topic. Local users can call the publishTopicMessage method to send messages in the topic, and remote users can call the subscribeTopic method to subscribe to the topic and receive messages.

This page introduces how to send and receive messages in a message channel or a user channel.

IRtmClient Signaling client instance

publishTopicMessage

Description

You can directly call the publishTopicMessage method to send messages to all online users subscribed to this channel. Even if you do not subscribe to the channel, you can still send messages in the channel.

After successfully calling this method, the SDK triggers a onMessageEvent event notification. Users who subscribe to the channel and enabled the event listener can receive this event notification. For details, see Event Listeners.

Method

You can call the publishTopicMessage method as follows:

virtual void publish(const char* channelName, const char* message, const size_t length, const PublishOptions& option, uint64_t& requestId) = 0;

The TopicMessageOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onPublishResult callback and return the API execution result through the following parameters:

Basic usage

Example 1: Send string messages to a specified channel.

PublishOptions options;
options.messageType = RTM_MESSAGE_TYPE_STRING;
options.customType = "PlainText";
options.channelTye = RTM_CHANNEL_TYPE_MESSAGE;
std::string message =  "hello world";
uint64_t requestId;
rtm_client->publish("channelName", message.c_str(), message.size(), options, requestId);

Example 2: Send byte messages to a specified channel.

PublishOptions options;
options.messageType = RTM_MESSAGE_TYPE_BINARY;
options.customType = "ByteArray";
options.channelTye = RTM_CHANNEL_TYPE_MESSAGE;

char message[5] = {0x00, 0x01, 0x02, 0x03, 0x04};

uint64_t requestId;
rtmClient->publish("channelName", message, 5, options, requestId);

Example 3: Send string messages to a specified user.

PublishOptions options;
options.messageType = RTM_MESSAGE_TYPE_STRING;
options.customType = "PlainText";
options.channelTye = RTM_CHANNEL_TYPE_USER;
std::string message =  "hello world";
uint64_t requestId;
rtm_client->publish("channelName", message.c_str(), message.size(), options, requestId);

Example 4: Send byte messages to a specified user.

PublishOptions options;
options.messageType = RTM_MESSAGE_TYPE_BINARY;
options.customType = "ByteArray";
options.channelTye = RTM_CHANNEL_TYPE_USER;

char message[5] = {0x00, 0x01, 0x02, 0x03, 0x04};

uint64_t requestId;
rtmClient->publish("channelName", message, 5, options, requestId);

Example 5: Asynchronous callback.

class RtmEventHandler : public IRtmEventHandler {
    void onPublishResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
          printf("publish message failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("publish message success\n");
        }
    }
};

Receive

Signaling provides event notifications for messages, states, and event changes. By listening for callbacks, you can receive messages and events within subscribed channels. As an example, the code snippet below shows how to receive messages from the user channel:

class RtmEventHandler : public IRtmEventHandler {
    void onMessageEvent(const MessageEvent& event) override {
 // User Channel Message
        if (event.channelType == RTM_CHANNEL_TYPE_USER) {
          printf("receive message from %s, message: %s\n", event.publisher, event.message);
        }
    }

 // ...
};

For information on how to add and set event listeners, see Event Listeners.

Presence

The presence feature provides the ability to monitor user online, offline, and user historical state change. With the Presence feature, you can get real-time access to the following information:

• Real-time event notification when a user joins or leaves a specified channel.
• Real-time event notification when the custom temporary user state changes.
• Query which channels a specified user has joined or subscribed to.
• Query which users have joined a specified channel and their temporary user state data.

IRtmPresence Presence instance

getOnlineUsers

Description

By calling the getOnlineUsers method, you can query real-time information about the number of online users, the list of online users, and the temporary state of online users in a specified channel.

Method

You can call the getOnlineUsers method as follows:

virtual void getOnlineUsers(const char* channelName, RTM_CHANNEL_TYPE channelType, const PresenceOptions& options, uint64_t& requestId) = 0;

The PresenceOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onGetOnlineUsersResult callback and return the API execution result through the following parameters:

The UserState data type contains the following properties:

StateItem data type contains the following properties:

Basic usage

// Method call
PresenceOptions options;
options.includeState = true;
options.includeUserId =true;
options.page = "yourBookMark";
uint64_t requestId;
rtmClient->getPresence()->getOnlineUsers("channelName", RTM_CHANNEL_TYPE_MESSAGE, options, requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onGetOnlineUsersResult(const uint64_t requestId, const UserState *userStateList, const size_t count, const char *nextPage, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("get online users failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("get online users success\n");
            for (int i = 0; i < count; i++) {
                printf("user: %s\n", userStateList[i].userId);
                for (int j = 0; j < userStateList[i].statesCount; j++) {
                    printf("key: %s value: %s\n", userStateList[i].states[j].key, userStateList[i].states[j].value);
                }
            }
        }
    }
};

getUserChannels

Description

In use-cases such as statistic analytics and debugging, you may need to know all the channels that a specified user has subscribed to or joined. Call the getUserChannels method to get the list of channels where the specified user is in real time.

Method

You can call the getUserChannels method as follows:

virtual void getUserChannels(const char* userId, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onGetUserChannelsResult callback and return the API execution result through the following parameters:

ChannelInfo data type contains the following properties:

Basic usage

// Method call
uint64_t requestId;
rtmClient->getPresence()->getUserChannels("tony", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onGetUserChannelsResult(const uint64_t requestId, const ChannelInfo *channels, const size_t count, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("get user channels failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("get user channels success\n");
            for (int i = 0; i < count; i++) {
                printf("channel: %s channel type: %d\n", channels[i].channelName, channels[i].channelType);
            }
        }
    }
};

setState

Description

To meet different requirements in different business use-cases for setting user states, Signaling provides the setState method to customize the temporary user state. Users can add custom states such as scores, game state, location, mood, and hosting state for themselves.

After successful setup, as long as the user keeps subscribing to the channel and stays online, the custom states can persist in the channel. setState method sets the temporary user state, and the state disappears when the user leaves the channel or disconnects from Signaling. If you need to restore user states when rejoining a channel or reconnecting, you need to cache the data locally in real time. If you want to permanently save user states, Agora recommends you use the setUserMetadata method of the storage function instead.

If a user modifies the temporary user state, Signaling triggers the RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED type of the onPresenceEvent event in real time. You can receive the event by subscribing to the channel and configuring the corresponding property.

Method

You can call the setState method as follows:

virtual void setState(const char* channelName, RTM_CHANNEL_TYPE channelType, const StateItem* items, size_t count, uint64_t& requestId) = 0;

StateItem data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onPresenceSetStateResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
std::vector<StateItem> items;
StateItem item;
item.key = "mood";
item.value = "pumped";
items.push_back(item);

uint64_t requestId;
rtmClient->getPresence()->setState("channelName", RTM_CHANNEL_TYPE_MESSAGE, items.data(), items.size(), requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onPresenceSetStateResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("SetState failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("SetState success\n");
        }
    }
};

getState

Description

To get the temporary user state of a specified user in the channel, you can use the getState method.

Method

You can call the getState method as follows:

virtual void getState(const char* channelName, RTM_CHANNEL_TYPE channelType, const char* userId, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onPresenceGetStateResult callback and return the API execution result through the following parameters:

The UserState data type contains the following properties:

StateItem data type contains the following properties:

Basic usage

// Method call
uint64_t requestId;
rtmClient->getPresence()->getState("channelName", RTM_CHANNEL_TYPE_MESSAGE, "tony", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onPresenceGetStateResult(const uint64_t requestId, const UserState &state, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("GetState failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("GetState user id: %s success\n", state.userId);
            for (int i = 0; i < state.statesCount; i++) {
                printf("key: %s, value: %s\n", state.states[i].key, state.states[i].value);
            }
        }
    }
};

removeState

Description

When a temporary user state is no longer needed, you can call the removeState method to remove one or more of your temporary states.

When the user state is removed, the user who has subscribed to the channel and enabled the presence event listener receives the RTM_PRESENCE_EVENT_TYPE_REMOTE_STATE_CHANGED type of onPresenceEvent event notification. See Event Listeners.

Method

You can call the removeState method as follows:

virtual void removeState(const char* channelName, RTM_CHANNEL_TYPE channelType, const char** keys, size_t count, uint64_t& requestId) = 0;

Asynchronous callback

After calling this method, the SDK triggers the onPresenceRemoveStateResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
std::vector<const char*> keys;
keys.push_back("key0");
keys.push_back("key1");
keys.push_back("key2");

uint64_t requestId;
rtmClient->getPresence()->removeState("channelName", RTM_CHANNEL_TYPE_MESSAGE, keys.data(), keys.size(), requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onPresenceRemoveStateResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("RemoveState failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("RemoveState success\n");
        }
    }
};

Storage

The storage feature provides a dynamic database mechanism that allows developers to dynamically set, store, update, and delete data such as channel metadata and user metadata.

IRtmStorage Storage instance

setChannelMetadata

Description

The setChannelMetadata method sets metadata for a message channel or stream channel. A channel can only have one set of metadata, but each set of metadata can have one or more metadata items. If you call this method multiple times, the SDK retrieves the key of the metadata items in turn and apply settings according to the following rules:

• If you set metadata with different key, the SDK adds each set of metadata in sequence according to the order of the method calls.
• If you set metadata with the same key, the value of the last setting overwrites the previous one.

Channel metadata also introduces the version control logic CAS (Compare And Set). This method provides two independent version control fields, and you can set one or more of them according to your actual business use-case:

• Enable version number verification for the entire set of channel metadata by setting the majorRevision property in the Metadata data type.
• Enable version number verification for a single metadata item by setting the revision property in the MetadataItem class.

When setting channel metadata or metadata items, you can control whether to enable version number verification by specifying the revision property:

• The default value of the revision property is -1, indicating that this method call does not perform any CAS verification. If the channel metadata or metadata item already exists, the latest value overwrites the previous one. If the channel metadata or metadata item does not exist, the SDK creates it.
• If the revision property is a positive integer, this method call performs the CAS verification. If the channel metadata or metadata item already exists, the SDK updates the corresponding value after the version number verification succeeds. If the channel metadata or metadata item does not exist, the SDK returns the error code.

After successfully setting channel metadata, users who subscribe to the channel and enable event listeners can receive the RTM_STORAGE_TYPE_CHANNEL type of the onStorageEvent event notification. See Event listeners.

Method

You can call the setChannelMetadata method as follows:

virtual void setChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType,
    const Metadata& data, const MetadataOptions& options,
    const char* lockName, uint64_t& requestId) = 0;

The MetadataOptions data type contains the following properties:

Asynchronous callback

After calling this method, the SDK triggers the onSetChannelMetadataResult callback and return the API execution result through the following parameters:

Basic usage

// Method call
Metadata metadata;
metadata.majorRevision = 174298270;
std::vector<agora::rtm::MetadataItem> items;
items.emplace_back(MetadataItem("Apple", "100", 174298200));
items.emplace_back(MetadataItem("Banana", "200", 174298100));
metadata.items = items.data();
metadata.itemCount = items.size();
MetadataOptions options;
options.recordTs = true;
options.recordUserId = true;
uint64_t requestId;
rtmClient->getStorage()->setChannelMetadata("channelName", RTM_CHANNEL_TYPE_MESSAGE, metadata, options, "lockName", requestId);

// Asynchronous callback
class RtmEventHandler : public IRtmEventHandler {
    void onSetChannelMetadataResult(const uint64_t requestId, const char *channelName, RTM_CHANNEL_TYPE channelType, RTM_ERROR_CODE errorCode) override {
        if (errorCode != RTM_ERROR_OK) {
            printf("SetChannelMetadata failed error is %d reason is %s\n", errorCode, getErrorReason(errorCode));
        } else {
            printf("SetChannelMetadata success\n");
        }
    }
};

getChannelMetadata

Description

The getChannelMetadata method can get the metadata of the specified channel.

Method

You can call the getChannelMetadata method as follows:

virtual void getChannelMetadata(
    const char* channelName, RTM_CHANNEL_TYPE channelType, uint64_t& requestId) = 0;

Asynchronous callback