Public Member Functions

abstract void release ()
 
abstract void login (@Nullable String token, @NonNull String userId, @Nullable ResultCallback< Void > resultCallback)
 
abstract void logout (@Nullable ResultCallback< Void > resultCallback)
 
abstract RtmMessage createMessage ()
 
abstract void sendMessageToPeer (@NonNull String peerId, @NonNull RtmMessage message, @Nullable ResultCallback< Void > resultCallback)
 
abstract void sendMessageToPeer (@NonNull String peerId, @NonNull RtmMessage message, @NonNull SendMessageOptions options, @Nullable ResultCallback< Void > resultCallback)
 
abstract RtmChannel createChannel (@NonNull String channelId, @NonNull RtmChannelListener channelListener) throws RuntimeException
 
abstract RtmCallManager getRtmCallManager ()
 
abstract void queryPeersOnlineStatus (Set< String > peerIds, ResultCallback< Map< String, Boolean >> resultCallback)
 
abstract void renewToken (String token, ResultCallback< Void > resultCallback)
 
abstract void setLocalUserAttributes (List< RtmAttribute > attributes, ResultCallback< Void > resultCallback)
 
abstract void addOrUpdateLocalUserAttributes (List< RtmAttribute > attributes, ResultCallback< Void > resultCallback)
 
abstract void deleteLocalUserAttributesByKeys (List< String > attributeKeys, ResultCallback< Void > resultCallback)
 
abstract void clearLocalUserAttributes (ResultCallback< Void > resultCallback)
 
abstract void getUserAttributes (String userId, ResultCallback< List< RtmAttribute >> resultCallback)
 
abstract void getUserAttributesByKeys (String userId, List< String > attributeKeys, ResultCallback< List< RtmAttribute >> resultCallback)
 
abstract int setParameters (String parameters)
 
abstract int setLogFile (String filePath)
 
abstract int setLogFilter (int filter)
 
abstract int setLogFileSize (int fileSizeInKBytes)
 

Static Public Member Functions

static RtmClient createInstance (@NonNull Context context, @NonNull String appId, @NonNull RtmClientListener eventListener) throws Exception
 
static String getSdkVersion ()
 

Static Public Attributes

static final int LOG_FILTER_OFF = 0
 
static final int LOG_FILTER_INFO = 0x0f
 
static final int LOG_FILTER_WARNING = 0x0e
 
static final int LOG_FILTER_ERROR = 0x0c
 
static final int LOG_FILTER_CRITICAL = 0x08
 

Detailed Description

The entry point of the Agora RTM SDK.

Member Function Documentation

◆ createInstance()

static RtmClient io.agora.rtm.RtmClient.createInstance ( @NonNull Context  context,
@NonNull String  appId,
@NonNull RtmClientListener  eventListener 
) throws Exception
static

Creates an RtmClient instance.

The Agora RTM SDK supports creating multiple RtmClient instances.

All methods in the RtmClient class are executed asynchronously.

Parameters
contextThe context of Android Activity.
appIdThe App ID issued to you from the Agora Dashboard. Apply for a new App ID from Agora if it is missing from your kit.
eventListenerAn RtmClientListener object that reports to the app on RTM SDK runtime events.
Returns
An RtmClient object.
Exceptions
ExceptionReturns an exception if appId is invalid (for example, its length is not 32 characters), or context or eventListener is null.

◆ release()

abstract void io.agora.rtm.RtmClient.release ( )
abstract

Releases all resources used by the RtmClient instance.

Note Do not call this method in any of your callbacks.

◆ login()

abstract void io.agora.rtm.RtmClient.login ( @Nullable String  token,
@NonNull String  userId,
@Nullable ResultCallback< Void >  resultCallback 
)
abstract

Logs in the Agora RTM system.

Note

Parameters
tokenThe token used to log in the Agora RTM system and used when dynamic authentication is enabled. Set token as null in the integration and test stages.
userIdThe user ID of the user logging in the Agora RTM system. The string length must be less than 64 bytes with the following character scope:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Note A userId cannot be empty, null or "null".
resultCallbackA ResultCallback object.
  • Success: The local user receives the onSuccess callback.
  • Failure: The local user receives the onFailure callback. See LoginError for the error codes.

◆ logout()

abstract void io.agora.rtm.RtmClient.logout ( @Nullable ResultCallback< Void >  resultCallback)
abstract

Logs out of the Agora RTM system.

Parameters
resultCallbackA ResultCallback object.
  • Success: The local user receives the onSuccess callback.
  • Failure: The local user receives the onFailure callback. See LogoutError for the error codes.

◆ createMessage()

abstract RtmMessage io.agora.rtm.RtmClient.createMessage ( )
abstract

Creates an RtmMessage instance.

Note The RtmMessage instance can be either for a channel message or for a peer-to-peer message.

Returns
The RtmMessage instance.

◆ sendMessageToPeer() [1/2]

abstract void io.agora.rtm.RtmClient.sendMessageToPeer ( @NonNull String  peerId,
@NonNull RtmMessage  message,
@Nullable ResultCallback< Void >  resultCallback 
)
abstract

Sends a peer-to-peer message to a specified remote user.

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 speed of 60 queries per second.

Success:

Failure: The local user receives the onFailure callback with an error. See PeerMessageError for the error codes.

Parameters
peerIdThe user ID of the remote user.
messageThe message to be sent. For information about creating a message, see RtmMessage.
resultCallbackA ResultCallback object.

◆ sendMessageToPeer() [2/2]

abstract void io.agora.rtm.RtmClient.sendMessageToPeer ( @NonNull String  peerId,
@NonNull RtmMessage  message,
@NonNull SendMessageOptions  options,
@Nullable ResultCallback< Void >  resultCallback 
)
abstract

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

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.

You can send messages, including peer-to-peer and channel messages, at a maximum speed of 60 queries per second.

Success:

Failure: The local user receives the onFailure callback with an error. See PeerMessageError for the error codes.

Parameters
peerIdThe user ID of the remote user. The string length must be less than 64 bytes with the following character scope:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Note A userId cannot be empty, null or "null".
messageThe message to be sent. For information about creating a message, see RtmMessage.
optionsOptions when sending the message to a peer. See SendMessageOptions.
resultCallbackA ResultCallback object.

◆ createChannel()

abstract RtmChannel io.agora.rtm.RtmClient.createChannel ( @NonNull String  channelId,
@NonNull RtmChannelListener  channelListener 
) throws RuntimeException
abstract

Creates an Agora RTM channel.

Note You can create multiple RtmChannel instances in an RtmClient instance, but you can only join a maximum of 20 channels at the same time. Please call the RtmChannel.release() method to release the resources of some RtmChannel instances that you no longer use. You can of course call the RtmClient.release() method to relase all resources used by the RtmClient, but we recommend that you NOT rely on the SDK to release an RtmChannel.

Parameters
channelIdThe unique channel name for the Agora RTM session. The string length must be less than 64 bytes with the following character scope:
  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9
  • Space
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Note A channelId cannot be empty or null.
channelListenerAn RtmChannelListener object.
  • Success: The SDK returns an RtmChannel instance.
  • Failure: The SDK returns null. channelId may be invalid, or a channel with the same channelId already exists.
Exceptions
RuntimeExceptionin any of the cases below:
  • The channelId is invalid.
  • The channelId is already in use.
  • The RtmClient instance is released.

◆ getRtmCallManager()

abstract RtmCallManager io.agora.rtm.RtmClient.getRtmCallManager ( )
abstract

Gets the Agora RTM call manager.

The Agora RTM SDK has one RtmCallManager instance for each RtmClient instance. Different RtmClient instances have different RtmCallManager instances.

Returns

◆ queryPeersOnlineStatus()

abstract void io.agora.rtm.RtmClient.queryPeersOnlineStatus ( Set< String >  peerIds,
ResultCallback< Map< String, Boolean >>  resultCallback 
)
abstract

Queries the online status of the specified user(s).

Parameters
peerIdsA list of the user IDs.
resultCallback

◆ renewToken()

abstract void io.agora.rtm.RtmClient.renewToken ( String  token,
ResultCallback< Void >  resultCallback 
)
abstract

Renews the token.

You are required to renew your Token when receiving the onTokenExpired callback. The call frequency limit for this method is 2 queries per second.

Parameters
tokenYour new Token.
resultCallback

◆ setLocalUserAttributes()

abstract void io.agora.rtm.RtmClient.setLocalUserAttributes ( List< RtmAttribute attributes,
ResultCallback< Void >  resultCallback 
)
abstract

Substitutes the local user's attributes with new ones.

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys, and clearLocalUserAttributes taken together: the call frequency limit is 10 queries every five seconds.

Parameters
attributesThe new attributes. See RtmAttribute.
resultCallback

◆ addOrUpdateLocalUserAttributes()

abstract void io.agora.rtm.RtmClient.addOrUpdateLocalUserAttributes ( List< RtmAttribute attributes,
ResultCallback< Void >  resultCallback 
)
abstract

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.

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys, and clearLocalUserAttributes taken together: the call frequency limit is 10 queries every five seconds.

Parameters
attributesThe attrubutes to be added or updated. See RtmAttribute.
resultCallback

◆ deleteLocalUserAttributesByKeys()

abstract void io.agora.rtm.RtmClient.deleteLocalUserAttributesByKeys ( List< String >  attributeKeys,
ResultCallback< Void >  resultCallback 
)
abstract

Deletes the local user's attributes using attribute keys.

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys, and clearLocalUserAttributes taken together: the call frequency limit is 10 queries every five seconds.

Parameters
attributeKeysA list of the attribute keys to be deleted.
resultCallback

◆ clearLocalUserAttributes()

abstract void io.agora.rtm.RtmClient.clearLocalUserAttributes ( ResultCallback< Void >  resultCallback)
abstract

Clears all attributes of the local user.

For setLocalUserAttributes, addOrUpdateLocalUserAttributes, deleteLocalUserAttributesByKeys, and clearLocalUserAttributes taken together: the call frequency limit is 10 queries every five seconds.

Parameters
resultCallback

◆ getUserAttributes()

abstract void io.agora.rtm.RtmClient.getUserAttributes ( String  userId,
ResultCallback< List< RtmAttribute >>  resultCallback 
)
abstract

Gets all attributes of a specified user.

For getUserAttributesgetUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Parameters
userIdThe user ID of the specified user.
resultCallback

◆ getUserAttributesByKeys()

abstract void io.agora.rtm.RtmClient.getUserAttributesByKeys ( String  userId,
List< String >  attributeKeys,
ResultCallback< List< RtmAttribute >>  resultCallback 
)
abstract

Gets the attributes of a specified user using attribute keys.

For getUserAttributesgetUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Parameters
userIdThe user ID of the specified user.
attributeKeysAn array of the attribute keys.
resultCallback

◆ setParameters()

abstract int io.agora.rtm.RtmClient.setParameters ( String  parameters)
abstract

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

The JSON options are not public by default. Agora is working on making commonly used JSON options public in a standard way.

Parameters
parametersSDK options in the JSON format.
Returns
  • 0: Success.
  • ≠0: Failure.

◆ setLogFile()

abstract int io.agora.rtm.RtmClient.setLogFile ( String  filePath)
abstract

Specifies the default path to the SDK log file.

Parameters
filePathFile path of the log file. The string of filePath is in UTF-8. The default log file path in the Android operating system is /sdcard/{Package name of the App}/agorartm.log.

Note

  • Ensure that the directory holding the log file exists and is writable.
  • Ensure that you call this method immediately after calling the createInstance method, otherwise the output log may be incomplete.
Returns
  • 0: Success.
  • ≠0: Failure.

◆ setLogFilter()

abstract int io.agora.rtm.RtmClient.setLogFilter ( int  filter)
abstract

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
filterSets the log filter level:
Returns
  • 0: Success.
  • ≠0: Failure.

◆ setLogFileSize()

abstract int io.agora.rtm.RtmClient.setLogFileSize ( int  fileSizeInKBytes)
abstract

Sets the log file size in KB.

The SDK has two log files, each with a default size of 512 KB. So, if you set fileSizeInBytes as 1024 KB, the SDK outputs log files with a total maximum size of 2 MB.

Note File size settings of less than 512 KB or greater than 10 MB will not take effect.

Parameters
fileSizeInKBytesThe SDK log file size (KB).
Returns
  • 0: Success.
  • ≠0: Failure.

◆ getSdkVersion()

static String io.agora.rtm.RtmClient.getSdkVersion ( )
static

Gets the SDK version.

Returns
The current version of the Agora RTM SDK in the string format. For example, 1.0.0.

Member Data Documentation

◆ LOG_FILTER_OFF

final int io.agora.rtm.RtmClient.LOG_FILTER_OFF = 0
static

0: Do not output any log information.

◆ LOG_FILTER_INFO

final int io.agora.rtm.RtmClient.LOG_FILTER_INFO = 0x0f
static

0x0f: Output CRITICAL, ERROR, WARNING, and INFO level log information.

◆ LOG_FILTER_WARNING

final int io.agora.rtm.RtmClient.LOG_FILTER_WARNING = 0x0e
static

0x0e: Output CRITICAL, ERROR, and WARNING level log information.

◆ LOG_FILTER_ERROR

final int io.agora.rtm.RtmClient.LOG_FILTER_ERROR = 0x0c
static

0x0c: Output CRITICAL and ERROR level log information.

◆ LOG_FILTER_CRITICAL

final int io.agora.rtm.RtmClient.LOG_FILTER_CRITICAL = 0x08
static

0x08: Output CRITICAL level log information.