Signaling (previously RTM) SDK v1.5.0 API Reference for Linux (C++)
Public Member Functions | Protected Member Functions | List of all members
agora::rtm::IRtmService Class Referenceabstract

#include <IAgoraRtmService.h>

Public Member Functions

virtual int  initialize (const char *appId, IRtmServiceEventHandler *eventHandler)=0
 
virtual void  addEventHandler (IRtmServiceEventHandler *eventHandler)=0
 
virtual void  removeEventHandler (IRtmServiceEventHandler *eventHandler)=0
 
virtual void  release (bool sync=false)=0
 
virtual int  login (const char *token, const char *userId)=0
 
virtual int  logout ()=0
 
virtual int  renewToken (const char *token)=0
 
virtual int  sendMessageToPeer (const char *peerId, const IMessage *message)=0
 
virtual int  downloadMediaToMemory (const char *mediaId, long long &requestId)=0
 
virtual int  downloadMediaToFile (const char *mediaId, const char *filePath, long long &requestId)=0
 
virtual int  cancelMediaDownload (long long requestId)=0
 
virtual int  cancelMediaUpload (long long requestId)=0
 
virtual int  sendMessageToPeer (const char *peerId, const IMessage *message, const SendMessageOptions &options)=0
 
virtual IChannel createChannel (const char *channelId, IChannelEventHandler *eventHandler)=0
 
virtual IRtmCallManager getRtmCallManager (IRtmCallEventHandler *eventHandler)=0
 
virtual IMessage createMessage ()=0
 
virtual IMessage createMessage (const char *message)=0
 
virtual IMessage createMessage (const uint8_t *rawData, int length)=0
 
virtual IMessage createMessage (const uint8_t *rawData, int length, const char *description)=0
 
virtual IFileMessage createFileMessageByMediaId (const char *mediaId)=0
 
virtual IImageMessage createImageMessageByMediaId (const char *mediaId)=0
 
virtual int  createFileMessageByUploading (const char *filePath, long long &requestId)=0
 
virtual int  createImageMessageByUploading (const char *filePath, long long &requestId)=0
 
virtual IRtmChannelAttribute createChannelAttribute ()=0
 
virtual int  setParameters (const char *parameters)=0
 
virtual int  queryPeersOnlineStatus (const char *peerIds[], int peerCount, long long &requestId)=0
 
virtual int  subscribePeersOnlineStatus (const char *peerIds[], int peerCount, long long &requestId)=0
 
virtual int  unsubscribePeersOnlineStatus (const char *peerIds[], int peerCount, long long &requestId)=0
 
virtual int  queryPeersBySubscriptionOption (PEER_SUBSCRIPTION_OPTION option, long long &requestId)=0
 
virtual int  setLocalUserAttributes (const RtmAttribute *attributes, int numberOfAttributes, long long &requestId)=0
 
virtual int  addOrUpdateLocalUserAttributes (const RtmAttribute *attributes, int numberOfAttributes, long long &requestId)=0
 
virtual int  deleteLocalUserAttributesByKeys (const char *attributeKeys[], int numberOfKeys, long long &requestId)=0
 
virtual int  clearLocalUserAttributes (long long &requestId)=0
 
virtual int  getUserAttributes (const char *userId, long long &requestId)=0
 
virtual int  getUserAttributesByKeys (const char *userId, const char *attributeKeys[], int numberOfKeys, long long &requestId)=0
 
virtual int  setChannelAttributes (const char *channelId, const IRtmChannelAttribute *attributes[], int numberOfAttributes, const ChannelAttributeOptions &options, long long &requestId)=0
 
virtual int  addOrUpdateChannelAttributes (const char *channelId, const IRtmChannelAttribute *attributes[], int numberOfAttributes, const ChannelAttributeOptions &options, long long &requestId)=0
 
virtual int  deleteChannelAttributesByKeys (const char *channelId, const char *attributeKeys[], int numberOfKeys, const ChannelAttributeOptions &options, long long &requestId)=0
 
virtual int  clearChannelAttributes (const char *channelId, const ChannelAttributeOptions &options, long long &requestId)=0
 
virtual int  getChannelAttributes (const char *channelId, long long &requestId)=0
 
virtual int  getChannelAttributesByKeys (const char *channelId, const char *attributeKeys[], int numberOfKeys, long long &requestId)=0
 
virtual int  getChannelMemberCount (const char *channelIds[], int channelCount, long long &requestId)=0
 
virtual int  setLogFile (const char *logfile)=0
 
virtual int  setLogFilter (LOG_FILTER_TYPE filter)=0
 
virtual int  setLogFileSize (int fileSizeInKBytes)=0
 

Protected Member Functions

virtual  ~IRtmService ()
 

Constructor & Destructor Documentation

◆ ~IRtmService()

virtual agora::rtm::IRtmService::~IRtmService ( )
inlineprotectedvirtual

Member Function Documentation

◆ initialize()

virtual int agora::rtm::IRtmService::initialize ( const char *  appId,
IRtmServiceEventHandler eventHandler 
)
pure virtual

Initializes an IRtmService instance.

All methods in the IRtmService class are executed asynchronously.

Parameters
appId The App ID issued by Agora to you. Apply for a new App ID from Agora if it is missing from your kit.
eventHandler An IRtmServiceEventHandler object that invokes callbacks to be passed to the application on Agora RTM SDK runtime events.
Returns

◆ addEventHandler()

virtual void agora::rtm::IRtmService::addEventHandler ( IRtmServiceEventHandler eventHandler )
pure virtual

Adds an IRtmServiceEventHandler object.

Parameters
eventHandler An IRtmServiceEventHandler object.

◆ removeEventHandler()

virtual void agora::rtm::IRtmService::removeEventHandler ( IRtmServiceEventHandler eventHandler )
pure virtual

Removes an IRtmServiceEventHandler object.

Parameters
eventHandler An IRtmServiceEventHandler object.

◆ release()

virtual void agora::rtm::IRtmService::release ( bool  sync = false )
pure virtual

Releases all resources used by the IRtmService instance.

◆ login()

virtual int agora::rtm::IRtmService::login ( const char *  token,
const char *  userId 
)
pure virtual

Logs in the Agora RTM system.

Note
Parameters
token Token used to log in the Agora RTM system and used when dynamic authentication is enabled. Set token as nil in the integration and test stages.
userId The user ID of the user logging in Agora's RTM system. The string must not exceed 64 bytes in length. It cannot be empty, null or "null". Supported characters:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0 to 9
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Returns

◆ logout()

virtual int agora::rtm::IRtmService::logout ( )
pure virtual

Logs out of the Agora RTM system.

The local user receives the onLogout callback. See LOGIN_ERR_CODE for the error codes.

Returns

◆ renewToken()

virtual int agora::rtm::IRtmService::renewToken ( const char *  token )
pure virtual

Renews the RTM Token of the SDK.

You are required to renew your RTM Token when receiving the onTokenExpired callback, and the onRenewTokenResult callback returns the result of this method call. The call frequency limit for this method is 2 calls per second.

Parameters
token Your new RTM Token. You need to generate the RTM Token yourself. See Generate an RTM Token.
Returns

◆ sendMessageToPeer() [1/2]

virtual int agora::rtm::IRtmService::sendMessageToPeer ( const char *  peerId,
const IMessage message 
)
pure virtual
Deprecated:
Sends a peer-to-peer message to a specified user (receiver).
Note
  • We do not recommend using this method to send a peer-to-peer message. Use sendMessageToPeer instead.
  • You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds.
Parameters
peerId User ID of the receiver.
message The message to be sent. For information about creating a message, see IMessage.
Returns

◆ downloadMediaToMemory()

virtual int agora::rtm::IRtmService::downloadMediaToMemory ( const char *  mediaId,
long long &  requestId 
)
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Downloads a file or image from the Agora server to the local memory by media ID.

The SDK returns the result of this method call by the onMediaDownloadToMemoryResult callback.

Note
  • This method applies to scenarios requiring quick access to the downloaded file or image.
  • The SDK releases the downloaded file or image immediately after returning the onMediaDownloadToMemoryResult callback.
Parameters
mediaId The media ID of the file or image on the Agora server.
requestId The unique ID of this download request.
Returns

◆ downloadMediaToFile()

virtual int agora::rtm::IRtmService::downloadMediaToFile ( const char *  mediaId,
const char *  filePath,
long long &  requestId 
)
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Downloads a file or image from the Agora server to a specified local directory by media ID.

The SDK returns the result of this method call by the onMediaDownloadToFileResult callback.

Parameters
mediaId The media ID of the file or image on the Agora server.
filePath The full path to the downloaded file or image. Must be in UTF-8.
requestId The unique ID of this download request.
Returns

◆ cancelMediaDownload()

virtual int agora::rtm::IRtmService::cancelMediaDownload ( long long  requestId )
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Cancels an ongoing file or image download task by request ID.

The SDK returns the result of this method call with the onMediaCancelResult callback.

Note
You can only cancel an ongoing download task. After a download task completes, the corresponding request ID is no longer valid and hence you cannot cancel it.
Parameters
requestId The unique ID of the download request to cancel.
Returns

◆ cancelMediaUpload()

virtual int agora::rtm::IRtmService::cancelMediaUpload ( long long  requestId )
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Cancels an ongoing file or image upload task by request ID.

The SDK returns the result of this method call with the onMediaCancelResult callback.

Note
You can only cancel an ongoing upload task. After an upload task completes, you cannot cancel it and the corresponding request ID is no longer valid.
Parameters
requestId The unique ID of the upload request to cancel.
Returns

◆ sendMessageToPeer() [2/2]

virtual int agora::rtm::IRtmService::sendMessageToPeer ( const char *  peerId,
const IMessage message,
const SendMessageOptions options 
)
pure virtual

Sends an (offline) peer-to-peer message to a specified user (receiver).

This method allows you to send a message to a specified user when he/she is offline. If you set a message as an offline message and the specified user is offline when you send it, the RTM server caches it. Please note that for now we only cache 200 offline messages for up to seven days for each receiver. When the number of the cached messages reaches this limit, the newest message overrides the oldest one.

If you use this method to send off a text message that starts off with AGORA_RTM_ENDCALL_PREFIX_<channelId>_<your additional information>, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace <channelId> with the channel ID from which you want to leave (end call), and replace <your additional information> with any additional information. Note that you must not put any "_" (underscore" in your additional information but you can set \<your additional information\> as empty "". - The \ref agora::rtm::IRtmServiceEventHandler::onSendMessageResult "onSendMessageResult" callback returns the result of this method call. - When the message arrives at the receiver, the receiver receives the \ref agora::rtm::IRtmServiceEventHandler::onMessageReceivedFromPeer "onMessageReceivedFromPeer" callback. If you use this method to send off a <i>text</i> message that starts off with AGORA_RTM_ENDCALL_PREFIX_\<channelId\>_\<your additional information\>, then this method is compatible with the endCall method of the legacy Agora Signaling SDK. Replace \<channelId\> with the channel ID from which you want to leave (end call), and replace \<your additional information\> with any additional information. Note that you must not put any "_" (underscore" in your additional information but you can set <your additional information> as empty "".

Note
You can send messages, including peer-to-peer and channel messages, at a maximum frequency of (RTM SDK for Windows C++) 180 calls every three seconds or (RTM SDK for Linux C++) 1500 calls every three seconds.
Parameters
peerId User ID of the receiver. The string must not exceed 64 bytes in length. It cannot be empty, null, or "null". Supported characters:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
message The message to be sent. For information about creating a message, See IMessage.
options Options when sending the message to a peer. See SendMessageOptions.
Returns

◆ createChannel()

virtual IChannel * agora::rtm::IRtmService::createChannel ( const char *  channelId,
IChannelEventHandler eventHandler 
)
pure virtual

Creates an Agora RTM channel.

  • If the method call succeeds, the SDK returns an IChannel instance.
  • If this method call fails, the SDK returns null.
Note
You can create multiple channels in an IRtmService instance. But you can only join a maximum of 20 channels at the same time. As a good practice, Agora recommends calling the release method to release all resources of an RTM channel that you no longer use.
Parameters
channelId The unique channel name. A channelId cannot be empty, null, or "null". Must be less than 64 bytes in length. Supported characters:
  • All lowercase English letters: a to z
  • All uppercase English letters: A to Z
  • All numeric characters: 0 to 9
  • The space character.
  • Punctuation characters and other symbols, including: "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
eventHandler See IChannelEventHandler.
Returns
  • An IChannel object: Success. If a channel with the same channelId does not exist, the method returns the created channel instance. If a channel with the same channelId already exists, the method returns the existing channel instance.
  • null: Failure. Possible reasons: The channelId is invalid or you have joined the maximum number of channels.

◆ getRtmCallManager()

virtual IRtmCallManager * agora::rtm::IRtmService::getRtmCallManager ( IRtmCallEventHandler eventHandler )
pure virtual

Gets an IRtmCallManager object.

Each IRtmService object corresponds to a unique IRtmCallManager object. That said, the IRtmCallManager object is IRtmService-specific.

Note
When you do no use IRtmCallManager, call the release method to release all of its resources.
Parameters
eventHandler An IRtmCallEventHandler object.
Returns
An IRtmCallManager object.

◆ createMessage() [1/4]

virtual IMessage * agora::rtm::IRtmService::createMessage ( )
pure virtual

Creates an empty text IMessage instance.

Note
  • An IMessage instance can be used either for a channel message or for a peer-to-peer message.
  • When you no longer need an IMessage instance, please call the release method to release all resources that it is using.
  • You can set the content of the text message at a later point using the setText method, but please ensure that the size of the text message does not exceed 32 KB.
Returns
An empty text IMessage instance.

◆ createMessage() [2/4]

virtual IMessage * agora::rtm::IRtmService::createMessage ( const char *  message )
pure virtual

Creates a text IMessage instance.

Note
  • An IMessage instance can be used either for a channel message or for a peer-to-peer message.
  • When you no longer need an IMessage instance, please call the release method to release all resources that it is using.
Parameters
message The text content of the message. Must not exceed 32 KB in length.
Returns
A text IMessage instance.

◆ createMessage() [3/4]

virtual IMessage * agora::rtm::IRtmService::createMessage ( const uint8_t *  rawData,
int  length 
)
pure virtual

Creates a raw IMessage instance.

Note
  • An IMessage instance can be used either for a channel message or for a peer-to-peer message.
  • When you no longer need an IMessage instance, please call the release method to release all resources that it is using.
  • You can set a brief text description of the raw message at a later point using the setText method, but please ensure that the size of the raw message and the description combined does not exceed 32 KB.
Parameters
rawData The starting address of the raw message.
length Length of the raw message. Must not exceed 32 KB in length.
Returns
A raw IMessage instance.

◆ createMessage() [4/4]

virtual IMessage * agora::rtm::IRtmService::createMessage ( const uint8_t *  rawData,
int  length,
const char *  description 
)
pure virtual

Creates a raw IMessage instance and sets its description.

Note
  • An IMessage instance can be used either for a channel message or for a peer-to-peer message.
  • When you no longer need an IMessage instance, please call the release method to release all resources that it is using.
  • You can set description as "" and add a brief text description of the raw message at a later point using the setText method, but please ensure that the size of the raw message and the description combined does not exceed 32 KB.
Parameters
rawData The starting address of the raw message.
length The length of the raw message. Must not exceed 32 KB in length.
description A brief text description of the raw message. If you set a text description, ensure that the size of the raw message and the description combined does not exceed 32 KB.
Returns
A raw IMessage instance with a brief text description.

◆ createFileMessageByMediaId()

virtual IFileMessage * agora::rtm::IRtmService::createFileMessageByMediaId ( const char *  mediaId )
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Creates an IFileMessage instance by media ID.

  • If you have at hand the media ID of a file on the Agora server, you can call this method to create an IFileMessage instance.
  • If you do not have a media ID, then you must call createFileMessageByUploading to get a corresponding IFileMessage instance by uploading a file to the Agora RTM server.
Parameters
mediaId The media ID of an uploaded file on the Agora server.
Returns
An IFileMessage instance.

◆ createImageMessageByMediaId()

virtual IImageMessage * agora::rtm::IRtmService::createImageMessageByMediaId ( const char *  mediaId )
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Creates an IImageMessage instance by media ID.

  • If you have at hand the media ID of an image on the Agora server, you can call this method to create an IImageMessage instance.
  • If you do not have a media ID, then you must call createImageMessageByUploading to get a corresponding IImageMessage instance by uploading an image to the Agora RTM server.
Parameters
mediaId The media ID of an uploaded image on the Agora server.
Returns
An IImageMessage instance.

◆ createFileMessageByUploading()

virtual int agora::rtm::IRtmService::createFileMessageByUploading ( const char *  filePath,
long long &  requestId 
)
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Gets an IFileMessage instance by uploading a file to the Agora server.

The SDK returns the result with the agora::rtm::IRtmServiceEventHandler::onFileMediaUploadResult callback. If success, this callback returns a corresponding IFileMessage instance.

Note
Parameters
filePath The full path to the local file to upload. Must be in UTF-8.
requestId The unique ID of this upload request.
Returns

◆ createImageMessageByUploading()

virtual int agora::rtm::IRtmService::createImageMessageByUploading ( const char *  filePath,
long long &  requestId 
)
pure virtual
Deprecated:
Deprecated as of v1.5.0. Agora recommends that you do not use it.

Gets an IImageMessage instance by uploading an image to the Agora server.

The SDK returns the result by the agora::rtm::IRtmServiceEventHandler::onImageMediaUploadResult callback. If success, this callback returns a corresponding ImageMessage instance.

  • If the uploaded image is in JPEG, JPG, BMP, or PNG format, the SDK calculates the width and height of the image. You can call getWidth and getHeight to get the calculated width and height.
  • Otherwise, you need to call setWidth and setHeight to set the width and height of the uploaded image by yourself.
Note
Parameters
filePath The full path to the local image to upload. Must be in UTF-8.
requestId The unique ID of the upload request.
Returns

◆ createChannelAttribute()

virtual IRtmChannelAttribute * agora::rtm::IRtmService::createChannelAttribute ( )
pure virtual

Creates an IRtmChannelAttribute instance.

Returns
An IRtmChannelAttribute instance.

◆ setParameters()

virtual int agora::rtm::IRtmService::setParameters ( const char *  parameters )
pure virtual

Provides the technical preview functionalities or special customizations by configuring the SDK with JSON options.

Note
The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way. Contact support@agora.io for more information.
Parameters
parameters SDK options in the JSON format.
Returns
  • 0: Success.
  • ≠0: Failure.

◆ queryPeersOnlineStatus()

virtual int agora::rtm::IRtmService::queryPeersOnlineStatus ( const char *  peerIds[],
int  peerCount,
long long &  requestId 
)
pure virtual

Queries the online status of the specified users.

  • Online: The user has logged in the Agora RTM system.
  • Offline: The user has logged out of the Agora RTM system.

The SDK returns the result by the onQueryPeersOnlineStatusResult callback.

Parameters
peerIds[] An array of the specified user IDs.
peerCount Length of the list.
requestId The unique ID of this request.
Returns

◆ subscribePeersOnlineStatus()

virtual int agora::rtm::IRtmService::subscribePeersOnlineStatus ( const char *  peerIds[],
int  peerCount,
long long &  requestId 
)
pure virtual

Subscribes to the online status of the specified users.

The SDK returns the result by the onSubscriptionRequestResult callback.

  • When the method call succeeds, the SDK returns the onPeersOnlineStatusChanged callback to report the online status of peers, to whom you subscribe.
  • When the online status of the peers, to whom you subscribe, changes, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed.
  • If the online status of the peers, to whom you subscribe, changes when the SDK is reconnecting to the server, the SDK returns the onPeersOnlineStatusChanged callback to report whose online status has changed when successfully reconnecting to the server.
Note
  • When you log out of the Agora RTM system, all the status that you subscribe to will be cleared. To keep the original subscription after you re-log in the system, you need to redo the whole subscription process.
  • When the SDK reconnects to the server from the state of being interupted, the SDK automatically subscribes to the peers and states before the interruption without human intervention.
Parameters
peerIds An array of the specified user IDs.
peerCount Length of the peer list.
requestId The unique ID of this request.
Returns

◆ unsubscribePeersOnlineStatus()

virtual int agora::rtm::IRtmService::unsubscribePeersOnlineStatus ( const char *  peerIds[],
int  peerCount,
long long &  requestId 
)
pure virtual

Unsubscribes from the online status of the specified users.

The SDK returns the result by the onSubscriptionRequestResult callback.

Parameters
peerIds An array of the specified user IDs.
peerCount Length of the peer list.
requestId The unique ID of this request.
Returns

◆ queryPeersBySubscriptionOption()

virtual int agora::rtm::IRtmService::queryPeersBySubscriptionOption ( PEER_SUBSCRIPTION_OPTION  option,
long long &  requestId 
)
pure virtual

Gets a list of the peers, to whose specific status you have subscribed.

The SDK returns the result by the onQueryPeersBySubscriptionOptionResult callback.

Parameters
option The status type, to which you have subscribed. See PEER_SUBSCRIPTION_OPTION.
requestId The unique ID of this request.
Returns

◆ setLocalUserAttributes()

virtual int agora::rtm::IRtmService::setLocalUserAttributes ( const RtmAttribute attributes,
int  numberOfAttributes,
long long &  requestId 
)
pure virtual

Substitutes the local user's attributes with new ones.

The SDK returns the result by the onSetLocalUserAttributesResult callback.

Note
For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
attributes The new attributes. See RtmAttribute.
numberOfAttributes The number of the attributes.
requestId The unique ID of this request.
Returns

◆ addOrUpdateLocalUserAttributes()

virtual int agora::rtm::IRtmService::addOrUpdateLocalUserAttributes ( const RtmAttribute attributes,
int  numberOfAttributes,
long long &  requestId 
)
pure virtual

Adds or updates the local user's attribute(s).

This method updates the local user's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) to the local user if it does not.

The SDK returns the result by the onAddOrUpdateLocalUserAttributesResult callback.

Note
For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
attributes The attrubutes to be added or updated. See RtmAttribute.
numberOfAttributes The number of the attributes.
requestId The unique ID of this request.
Returns

◆ deleteLocalUserAttributesByKeys()

virtual int agora::rtm::IRtmService::deleteLocalUserAttributesByKeys ( const char *  attributeKeys[],
int  numberOfKeys,
long long &  requestId 
)
pure virtual

Deletes the local user's attributes by attribute keys.

The SDK returns the result by the onDeleteLocalUserAttributesResult callback.

Note
For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
attributeKeys An array of the attribute keys to be deleted.
numberOfKeys Number of the attribute keys.
requestId The unique ID of this request.
Returns

◆ clearLocalUserAttributes()

virtual int agora::rtm::IRtmService::clearLocalUserAttributes ( long long &  requestId )
pure virtual

Clears all attributes of the local user.

The SDK returns the result by the onClearLocalUserAttributesResult callback.

Note
For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys and clearLocalUserAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
requestId The unique ID of this request.
Returns

◆ getUserAttributes()

virtual int agora::rtm::IRtmService::getUserAttributes ( const char *  userId,
long long &  requestId 
)
pure virtual

Gets all attributes of a specified user.

The SDK returns the result by the onGetUserAttributesResult callback.

Note
For getUserAttributes and getUserAttributesByKeys taken together, the maximum call frequency is (RTM SDK for Windows C++) 40 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds.
Parameters
userId The user ID of the specified user.
requestId The unique ID of this request.
Returns

◆ getUserAttributesByKeys()

virtual int agora::rtm::IRtmService::getUserAttributesByKeys ( const char *  userId,
const char *  attributeKeys[],
int  numberOfKeys,
long long &  requestId 
)
pure virtual

Gets the attributes of a specified user by attribute keys.

The SDK returns the result by the onGetUserAttributesResult callback.

Note
For getUserAttributes and getUserAttributesByKeys taken together, the maximum call frequency is (RTM SDK for Windows C++) 40 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds.
Parameters
userId The user ID of the specified user.
attributeKeys An array of the attribute keys.
numberOfKeys The number of the attribute keys.
requestId The unique ID of this request.
Returns

◆ setChannelAttributes()

virtual int agora::rtm::IRtmService::setChannelAttributes ( const char *  channelId,
const IRtmChannelAttribute attributes[],
int  numberOfAttributes,
const ChannelAttributeOptions options,
long long &  requestId 
)
pure virtual

Resets the attributes of a specified channel.

The SDK returns the result by the onSetChannelAttributesResult callback.

Note
  • You do not have to join the specified channel to update its attributes.
  • The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
  • If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
  • For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
channelId The channel ID of the specified channel.
attributes An array of channel attributes. See IRtmChannelAttribute.
numberOfAttributes The total number of the channel attributes.
options Options for this attribute operation. See ChannelAttributeOptions.
requestId The unique ID of this request.
Returns

◆ addOrUpdateChannelAttributes()

virtual int agora::rtm::IRtmService::addOrUpdateChannelAttributes ( const char *  channelId,
const IRtmChannelAttribute attributes[],
int  numberOfAttributes,
const ChannelAttributeOptions options,
long long &  requestId 
)
pure virtual

Adds or updates the attribute(s) of a specified channel.

This method updates the specified channel's attribute(s) if it finds that the attribute(s) has/have the same key(s), or adds attribute(s) to the channel if it does not.

The SDK returns the result by the onAddOrUpdateChannelAttributesResult callback.

Note
  • You do not have to join the specified channel to update its attributes.
  • The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
  • If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
  • For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
channelId The channel ID of the specified channel.
attributes An array of channel attributes. See IRtmChannelAttribute.
numberOfAttributes The total number of the channel attributes.
options Options for this attribute operation. See ChannelAttributeOptions.
requestId The unique ID of this request.
Returns

◆ deleteChannelAttributesByKeys()

virtual int agora::rtm::IRtmService::deleteChannelAttributesByKeys ( const char *  channelId,
const char *  attributeKeys[],
int  numberOfKeys,
const ChannelAttributeOptions options,
long long &  requestId 
)
pure virtual

Deletes the attributes of a specified channel by attribute keys.

The SDK returns the result by the onDeleteChannelAttributesResult callback.

Note
  • You do not have to join the specified channel to update its attributes.
  • The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
  • If more than one user can update the channel attributes, then Agora recommends calling getChannelAttributes to update the cache before calling this method.
  • For setChannelAttributes, addOrUpdateChannelAttributes, deleteChannelAttributesByKeys and clearChannelAttributes taken together: the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 100 calls every five seconds.
Parameters
channelId The channel ID of the specified channel.
attributeKeys An array of channel attribute keys.
numberOfKeys The total number of the channel attributes.
options Options for this attribute operation. See ChannelAttributeOptions.
requestId The unique ID of this request.
Returns

◆ clearChannelAttributes()

virtual int agora::rtm::IRtmService::clearChannelAttributes ( const char *  channelId,
const ChannelAttributeOptions options,
long long &  requestId 
)
pure virtual

Clears all attributes of a specified channel.

The SDK returns the result by the onClearChannelAttributesResult callback.

Note
Parameters
channelId The channel ID of the specified channel.
options Options for this attribute operation. See ChannelAttributeOptions.
requestId The unique ID of this request.
Returns

◆ getChannelAttributes()

virtual int agora::rtm::IRtmService::getChannelAttributes ( const char *  channelId,
long long &  requestId 
)
pure virtual

Gets all attributes of a specified channel.

The SDK returns the result by the onGetChannelAttributesResult callback.

Note
  • You do not have to join the specified channel to get its attributes.
  • For getChannelAttributes and getChannelAttributesByKeys taken together, the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds.
Parameters
channelId The channel ID of the specified channel.
requestId The unique ID of this request.
Returns

◆ getChannelAttributesByKeys()

virtual int agora::rtm::IRtmService::getChannelAttributesByKeys ( const char *  channelId,
const char *  attributeKeys[],
int  numberOfKeys,
long long &  requestId 
)
pure virtual

Gets the attributes of a specified channel by attribute keys.

The SDK returns the result by the onGetChannelAttributesResult callback.

Note
  • You do not have to join the specified channel to get its attributes.
  • For getChannelAttributes and getChannelAttributesByKeys taken together, the maximum call frequency is (RTM SDK for Windows C++) 10 calls every five seconds or (RTM SDK for Linux C++) 400 calls every five seconds.
Parameters
channelId The channel ID of the specified channel.
attributeKeys An array of attribute keys.
numberOfKeys The total number of the attribute keys.
requestId The unique ID of this request.
Returns

◆ getChannelMemberCount()

virtual int agora::rtm::IRtmService::getChannelMemberCount ( const char *  channelIds[],
int  channelCount,
long long &  requestId 
)
pure virtual

Gets the member count of specified channels.

The SDK returns the result by the onGetChannelMemberCountResult callback.

Note
  • The call frequency limit for this method is one query per second.
  • We do not support getting the member counts of more than 32 channels in one method call.
  • You do not have to join the specified channels to call this method.
Parameters
channelIds An array of the specified channel IDs.
channelCount The total number of the channels.
requestId The unique ID of this request.
Returns

◆ setLogFile()

virtual int agora::rtm::IRtmService::setLogFile ( const char *  logfile )
pure virtual

Specifies the default path to the SDK log file.

Note
  • Ensure that the directory holding the log file exists and is writable.
  • Ensure that you call this method immediately after calling the initialize method to initialize an IRtmService instance, otherwise the output log may be incomplete.
  • For the Linux C++ platform, agorartm.log is in the current working directory.
Parameters
logfile The absolute file path to the log file. The string of logfile is in UTF-8.
Returns
  • 0: Success.
  • ≠0: Failure.

◆ setLogFilter()

virtual int agora::rtm::IRtmService::setLogFilter ( LOG_FILTER_TYPE  filter )
pure virtual

Sets the output log level of the SDK.

You can use one or a combination of the filters. The log level follows the sequence of OFF, CRITICAL, ERROR, WARNING, and INFO. Choose a level to see the logs preceding that level. If, for example, you set the log level to WARNING, you see the logs within levels CRITICAL, ERROR, and WARNING.

Parameters
filter The log filter level. See LOG_FILTER_TYPE.
Returns
  • 0: Success.
  • ≠0: Failure.

◆ setLogFileSize()

virtual int agora::rtm::IRtmService::setLogFileSize ( int  fileSizeInKBytes )
pure virtual

Sets the size of a single log file. The SDK has two log files with the same size.

Parameters
fileSizeInKBytes The size of a single log file (KB). For RTM C++ SDK for Windows, the default is 10240 (KB). For RTM C++ SDK for Linux, the default is 102400 (KB). The value range is [512 KB, 1 GB].
Returns
  • 0: Success.
  • ≠0: Failure.