#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

0: Success.
≠0: Failure. See INIT_ERR_CODE.

◆ 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.

If this method call succeeds, the local user receives the onLoginSuccess callback.
If this method call fails, the local user receives the onLoginFailure callback. See LOGIN_ERR_CODE for the error codes.

Note

If you log in with the same user ID from a different instance, you will be kicked out of your previous login and removed from previously joined channels.
The call frequency limit for this method is 2 queries per second.
Only after you successfully call this method (when the local user receives the onLoginSuccess callback), can you call the key RTM methods except:

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

0: Success.
≠0: Failure. See LOGIN_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See LOGOUT_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See RENEW_TOKEN_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See PEER_MESSAGE_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See DOWNLOAD_MEDIA_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See DOWNLOAD_MEDIA_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See CANCEL_MEDIA_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See CANCEL_MEDIA_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See PEER_MESSAGE_ERR_CODE for the error codes.

◆ 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

If you have at hand the media ID of a file on the Agora server, you can call createFileMessageByMediaId to create an IFileMessage instance.
To cancel an ongoing file upload task, call cancelMediaUpload.

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

0: Success.
≠0: Failure. See UPLOAD_MEDIA_ERR_CODE for the error codes.

◆ 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

If you have at hand the media ID of an image on the Agora server, you can call createImageMessageByMediaId to create an IImageMessage instance.
To cancel an ongoing image upload task, call cancelMediaUpload.

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

0: Success.
≠0: Failure. See UPLOAD_MEDIA_ERR_CODE for the error codes.

◆ 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

0: Success.
≠0: Failure. See QUERY_PEERS_ONLINE_STATUS_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See PEER_SUBSCRIPTION_STATUS_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See PEER_SUBSCRIPTION_STATUS_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See QUERY_PEERS_BY_SUBSCRIPTION_OPTION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

You do not have to join the specified channel to clear its attributes.
The attributes of a channel will be cleared if the channel remains empty (has no members) for a couple of minutes.
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.
options	Options for this attribute operation. See ChannelAttributeOptions.
requestId	The unique ID of this request.

Returns

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See ATTRIBUTE_OPERATION_ERR for the error codes.

◆ 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

0: Success.
≠0: Failure. See GET_CHANNEL_MEMBER_COUNT_ERR_CODE for the error codes.

◆ 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.

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ ~IRtmService()

Member Function Documentation

◆ initialize()

◆ addEventHandler()

◆ removeEventHandler()

◆ release()

◆ login()

◆ logout()

◆ renewToken()

◆ sendMessageToPeer() [1/2]

◆ downloadMediaToMemory()

◆ downloadMediaToFile()

◆ cancelMediaDownload()

◆ cancelMediaUpload()

◆ sendMessageToPeer() [2/2]

◆ createChannel()

◆ getRtmCallManager()

◆ createMessage() [1/4]

◆ createMessage() [2/4]

◆ createMessage() [3/4]

◆ createMessage() [4/4]

◆ createFileMessageByMediaId()

◆ createImageMessageByMediaId()

◆ createFileMessageByUploading()

◆ createImageMessageByUploading()

◆ createChannelAttribute()

◆ setParameters()

◆ queryPeersOnlineStatus()

◆ subscribePeersOnlineStatus()

◆ unsubscribePeersOnlineStatus()

◆ queryPeersBySubscriptionOption()

◆ setLocalUserAttributes()

◆ addOrUpdateLocalUserAttributes()

◆ deleteLocalUserAttributesByKeys()

◆ clearLocalUserAttributes()

◆ getUserAttributes()

◆ getUserAttributesByKeys()

◆ setChannelAttributes()

◆ addOrUpdateChannelAttributes()

◆ deleteChannelAttributesByKeys()

◆ clearChannelAttributes()

◆ getChannelAttributes()

◆ getChannelAttributesByKeys()

◆ getChannelMemberCount()

◆ setLogFile()

◆ setLogFilter()

◆ setLogFileSize()