Quickstart

Understand the tech

To use Signaling features in your app, you initialize a Signaling client instance and add event listeners. To connect to Signaling, you login using an authentication token. To send a message to a message channel, you publish the message. Signaling creates a channel when a user subscribes to it. To receive messages other users publish to a channel, your app listens for events.

To create a pub/sub session for Signaling, implement the following steps in your app:

Prerequisites

To implement the code presented on this page you need to have:

• An Agora account and project.
• Enabled Signaling in Agora Console

• A device running Linux Ubuntu 14.04 or above; 18.04+ is recommended.
• At least 2 GB of memory.
• cmake 3.6.0 or above.

• Ensure that a firewall is not blocking your network communication.

Project setup

Create a project

Create the following folder structure for your project:

RTMProject/
├── include/
└── lib/

Integrate the SDK

To integrate the Linux C++ Signaling SDK into your project:

1. Download the latest version of the SDK and unzip it.

   To integrate Signaling SDK 2.2.1 or later, and RTC SDK 4.3.0 or later in the same project, refer to handle integration issues.

2. Copy the files in the SDK package to the project folder as follows:

   • Copy the /rtm/sdk/libagora_rtm_sdk.so file to the project's lib folder.
   • Copy all *.h files in /rtm/sdk/high_level_api/include to the project's include folder.

3. To use CMake to compile the project, create the following files in the RTMProject folder:

   • CMakeLists.txt

     # CMakeLists.txt
     cmake_minimum_required (VERSION 2.8)
     project(RTMProject)
     set(TARGET_NAME RTMQuickStart)
     set(SOURCES RTMQuickStart.cpp)
     set(HEADERS)
     set(TARGET_BUILD_TYPE "Debug")
     set(CMAKE_CXX_FLAGS "-fPIC -O2 -g -std=c++11 -msse2")
     include_directories(${CMAKE_SOURCE_DIR}/include)
     link_directories(${CMAKE_SOURCE_DIR}/lib)
     add_executable(${TARGET_NAME} ${SOURCES} ${HEADERS})
     target_link_libraries(${TARGET_NAME} agora_rtm_sdk pthread)

   • clean_build.sh

     # clean_build.sh
     rm -fr build
     mkdir -p build
     cd build
     cmake ..
     make
     cd ..

Implement Signaling

A complete code sample that implements the basic features of Signaling is presented here for your reference. To use the sample code, create a new file named RTMQuickStart.cpp in the RTMProject folder and add the following code:

Follow the implementation steps to understand the core API calls in the sample code or use the snippets in your own code.

Include the header file

To use Signaling APIs in your project, include the IAgoraRtmClient header file:

#include "IAgoraRtmClient.h"

Initialize the Signaling engine

Before calling any other Signaling SDK API, initialize an IRtmClient object instance.

std::string userID;
std::getline(std::cin, userID);

RtmConfig config;
config.appId = APP_ID.c_str();
config.userId = userID.c_str();
config.eventHandler = eventHandler_.get();

// Create an IRtmClient instance
int errorCode = 0;
rtmClient_ = createAgoraRtmClient(config, errorCode);
if (!rtmClient_ || errorCode != 0) {
  std::cout << RED <<"error creating rtm service!" << std::endl;
  exit(0);
}

Add an event listener

The event listener enables you to implement the processing logic in response to Signaling events. Use the following code to handle event notifications or display received messages:

void onLoginResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
  cbPrint("onLoginResult, request id: %lld, errorCode: %d", requestId, errorCode);
}

void onLogoutResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) {
  cbPrint("onLogoutResult, request id: %lld, errorCode: %d", requestId, errorCode);
}

void onLinkStateEvent(const LinkStateEvent& event) override {
  cbPrint("onLinkStateEvent, state: %d -> %d, operation: %d, reason: %s", event.previousState, event.currentState, event.operation, event.reason);
}

void onPublishResult(const uint64_t requestId, RTM_ERROR_CODE errorCode) override {
  cbPrint("onPublishResult request id: %lld result: %d", requestId, errorCode);
}

void onMessageEvent(const MessageEvent &event) override {
  cbPrint("receive message from: %s, message: %s", event.publisher, event.message);
}

void onSubscribeResult(const uint64_t requestId, const char *channelName, RTM_ERROR_CODE errorCode) override {
  cbPrint("onSubscribeResult: channel:%s, request id: %lld result: %d", channelName, requestId, errorCode);
}

void onUnsubscribeResult(const uint64_t requestId, const char *channelName, RTM_ERROR_CODE errorCode) override {
  cbPrint("onUnsubscribeResult: channel:%s, request id: %lld result: %d", channelName, requestId, errorCode);
}

Log in to Signaling

To connect to Signaling and access Signaling network resources, such as sending messages, and subscribing to channels, call login.

During a login operation, the client attempts to establish a connection with Signaling. Once the connection is established, the client transmits heartbeat information to the Signaling server at fixed intervals to keep the client active until the client actively logs out or is disconnected. The connection is interrupted when timeout occurs. During this period, users may freely access the Signaling network resources subject to their own permissions and usage restrictions.

// Log in to Signaling
uint64_t requestId = 0;
rtmClient_->login(TOKEN.c_str(), requestId);

After you call this method, the SDK triggers the onLoginResult callback and returns the API call result.

Use the login return value, or listen to the onLinkStateEvent event notification to confirm that login is successful or obtain the error code and cause of login failure. When performing a login operation, the client's network connection state is RTM_LINK_STATE_CONNECTING. After a successful login, the state is updated to RTM_LINK_STATE_CONNECTED.

Send a message

To distribute a message to all subscribers of a message channel, call publish. The following code sends a string type message.

// Publish a message to the channel
void publishMessage(const std::string& channelName, const std::string& message) {
  PublishOptions options;
  options.messageType = RTM_MESSAGE_TYPE_STRING;
  uint64_t requestId;
  rtmClient_->publish(channelName.c_str(), message.c_str(), message.size(), options, requestId);
}

Subscribe and unsubscribe

To receive messages sent to a channel, call subscribe to subscribe to channel messages:

// Subscribe to a channel
void subscribeChannel(const std::string& channelName) {
  uint64_t requestId = 0;
  rtmClient_->subscribe(channelName.c_str(), SubscribeOptions(), requestId);
}

When you no longer need to receive messages from a channel, call unsubscribe to unsubscribe from the channel:

// Unsubscribe from a channel
void unsubscribeChannel(const std::string& channelName) {
  uint64_t requestId = 0;
  rtmClient_->unsubscribe(channelName.c_str(), requestId);
}

For more information about sending and receiving messages see Message channels and Stream channels.

Log out of Signaling

When a user no longer needs to use Signaling, call logout. Logging out means closing the connection between the client and Signaling. The user is automatically logged out or unsubscribed from all message and stream channels. Other users in the channel receive an onPresenceEvent notification of the user leaving the channel.

// Log out of Signaling
void logout() {
  uint64_t requestId = 0;
  rtmClient_->logout(requestId);
}

// Clean up
rtmClient_->release();

Test Signaling

Take the following steps to test the sample code:

1. Generate a temporary token for your project.

2. In your code, replace <Your App ID> with your app ID from Agora Console and <Your token> with the generated token. Save the project. Make sure Signaling is activated for your project in Agora Console.

3. In the terminal, run the following command to compile the project:

   sh +x clean_build.sh

4. Use the following commands to navigate to the build folder and run the app:

   cd build
   ./RTMQuickStart

   You see menu options to subscribe, unsubscribe, publish, and logout.

5. Follow the prompts to subscribe to a channel.

6. Run another instance of the app using a different user ID. Follow the prompts to publish a message to the same channel that you subscribed to from the other instance.

7. You see the message displayed in the instance that you used to subscribe to the channel.

   Congratulations! You have successfully integrated Signaling into your project.

Reference

This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.

Token authentication

In this guide you retrieve a temporary token from Agora Console. To understand how to create an authentication server for development purposes, see Secure authentication with tokens.

Sample project

Agora provides an open source sample project on GitHub for your reference. Download it or view the source code for a more detailed example.

API reference

• API reference
• Event listeners