AgoraRtmKit Class Reference

Inherits from NSObject
Declared in AgoraRtmKit.h

Overview

The entry point of the Agora RTM system.

  agoraRtmDelegate

AgoraRtmDelegate enables Agora RTM callback event notifications to your app.

@property (atomic, weak, nullable) id<AgoraRtmDelegate> agoraRtmDelegate

Declared In

AgoraRtmKit.h

  __deprecated

*DEPRECATED** The property for managing channels for the local user.

@property (atomic, readonly, nullable) NSMutableDictionary<NSString*AgoraRtmChannel*> *__deprecated

Declared In

AgoraRtmKit.h

– initWithAppId:delegate:

Creates and initializes an AgoraRtmKit instance.

- (instancetype _Nullable)initWithAppId:(NSString *_Nonnull)appId delegate:(id<AgoraRtmDelegate> _Nullable)delegate

Parameters

appId

The App ID issued to you from the Agora Console. Apply for a new App ID from Agora if it is missing from your kit.

delegate

AgoraRtmDelegate invokes callbacks to be passed to the app on Agora RTM SDK runtime events.

Return Value

  • An AgoraRtmKit instance if this method call succeeds.
  • nil if this method call fails for the reason that the length of the appId is not 32 characters.

Discussion

The Agora RTM SDK supports creating multiple AgoraRtmKit instances. All methods in the AgoraRtmKit class, except the destroyChannelWithId method, are executed asynchronously.

Declared In

AgoraRtmKit.h

– loginByToken:user:completion:

Logs in the Agora RTM system.

- (void)loginByToken:(NSString *_Nullable)token user:(NSString *_Nonnull)userId completion:(AgoraRtmLoginBlock _Nullable)completionBlock

Parameters

token

A token generated by the app server and used to log in the Agora RTM system. token is used when dynamic authentication is enabled. Set token as nil at the integration and test stages.

userId

The 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:

  • 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: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”

NOTE

A userId cannot be empty, nil, or “null”.

completionBlock

AgoraRtmLoginBlock returns the result of this method call. See AgoraRtmLoginErrorCode for the error codes.

Discussion

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 two queries per second.
  • Only after you successfully call this method and receives the AgoraRtmLoginErrorOk error code, can you call the key RTM methods except:

After the app calls this method, the local user receives the connectionStateChanged callback and switches to the AgoraRtmConnectionStateConnecting state.

Declared In

AgoraRtmKit.h

– logoutWithCompletion:

Logs out of the Agora RTM system.

- (void)logoutWithCompletion:(AgoraRtmLogoutBlock _Nullable)completionBlock

Parameters

completionBlock

AgoraRtmLogoutBlock returns the result of this method call. See AgoraRtmLogoutErrorCode for the error codes.

Discussion

Declared In

AgoraRtmKit.h

– renewToken:completion:

Renews the RTM Token of the SDK.

- (void)renewToken:(NSString *_Nonnull)token completion:(AgoraRtmRenewTokenBlock _Nullable)completionBlock

Parameters

token

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

completionBlock

AgoraRtmRenewTokenBlock returns the result of this method call.

Discussion

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

Declared In

AgoraRtmKit.h

– sendMessage:toPeer:completion:

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

- (void)sendMessage:(AgoraRtmMessage *_Nonnull)message toPeer:(NSString *_Nonnull)peerId completion:(AgoraRtmSendPeerMessageBlock _Nullable)completionBlock

Parameters

message

The message to be sent. For information about creating a message, see AgoraRtmMessage.

peerId

The ID of the remote user.

completionBlock

AgoraRtmSendPeerMessageBlock returns the result of this method call. See AgoraRtmSendPeerMessageErrorCode for the error codes.

Discussion

DEPRECATED

We do not recommend using this method to send a peer-to-peer message. Use sendMessage instead.

Declared In

AgoraRtmKit.h

– downloadMediaToMemory:withRequest:completion:

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

- (void)downloadMediaToMemory:(NSString *_Nonnull)mediaId withRequest:(long long *)requestId completion:(AgoraRtmDownloadMediaToMemoryBlock _Nullable)completionBlock

Parameters

mediaId

The media ID of the file or image on the Agora server.

requestId

The unique ID to identify one request.

completionBlock

AgoraRtmDownloadMediaToMemoryBlock returns the result of this method call. See AgoraRtmDownloadMediaErrorCode for the error codes.

Discussion

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 AgoraRtmDownloadMediaToMemoryBlock callback.

Declared In

AgoraRtmKit.h

– downloadMedia:toFile:withRequest:completion:

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

- (void)downloadMedia:(NSString *_Nonnull)mediaId toFile:(NSString *_Nonnull)filePath withRequest:(long long *)requestId completion:(AgoraRtmDownloadMediaToFileBlock _Nullable)completionBlock

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.

completionBlock

AgoraRtmDownloadMediaToFileBlock returns the result of this method call. See AgoraRtmDownloadMediaErrorCode for the error codes.

Declared In

AgoraRtmKit.h

– createFileMessageByUploading:withRequest:completion:

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

- (void)createFileMessageByUploading:(NSString *_Nonnull)filePath withRequest:(long long *)requestId completion:(AgoraRtmUploadFileMediaBlock _Nullable)completionBlock

Parameters

filePath

The full path to the local file to upload. Must be in UTF-8.

requestId

The unique ID of this upload request.

completionBlock

AgoraRtmUploadFileMediaBlock returns the result of this method call. See AgoraRtmUploadMediaErrorCode for the error codes.

Discussion

The SDK returns the result with the AgoraRtmUploadFileMediaBlock callback. If success, this callback returns a corresponding AgoraRtmMessage instance, and then you can downcast it to AgoraRtmFileMessage according to its type.

NOTE

Declared In

AgoraRtmKit.h

– createImageMessageByUploading:withRequest:completion:

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

- (void)createImageMessageByUploading:(NSString *_Nonnull)filePath withRequest:(long long *)requestId completion:(AgoraRtmUploadImageMediaBlock _Nullable)completionBlock

Parameters

filePath

The full path to the local image to upload. Must be in UTF-8.

requestId

The unique ID of the upload request.

completionBlock

AgoraRtmUploadImageMediaBlock returns the result of this method call. See AgoraRtmUploadMediaErrorCode for the error codes.

Discussion

The SDK returns the result by the AgoraRtmUploadImageMediaBlock callback. If success, this callback returns a corresponding AgoraRtmMessage instance, and then you can downcast it to AgoraRtmImageMessage according to its type.

  • If the uploaded image is in JPEG, JPG, BMP, or PNG format, the SDK calculates the width and height of the image. You can get the calculated width and height from the received AgoraRtmImageMessage instance.
  • Otherwise, you need to set the width and height of the uploaded image within the received AgoraRtmImageMessage instance by yourself.

NOTE

Declared In

AgoraRtmKit.h

– cancelMediaDownload:completion:

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

- (void)cancelMediaDownload:(long long)requestId completion:(AgoraRtmCancelMediaBlock _Nullable)completionBlock

Parameters

requestId

The unique Id to identify one request

completionBlock

AgoraRtmCancelMediaBlock returns the result of this method call. See AgoraRtmCancelMediaErrorCode for the error codes.

Discussion

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.

Declared In

AgoraRtmKit.h

– cancelMediaUpload:completion:

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

- (void)cancelMediaUpload:(long long)requestId completion:(AgoraRtmCancelMediaBlock _Nullable)completionBlock

Parameters

requestId

The unique ID of the upload request to cancel.

completionBlock

AgoraRtmCancelMediaBlock returns the result of this method call. See AgoraRtmCancelMediaErrorCode for the error codes.

Discussion

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.

Declared In

AgoraRtmKit.h

– createFileMessageByMediaId:

Creates an AgoraRtmFileMessage instance by media ID.

- (AgoraRtmFileMessage *)createFileMessageByMediaId:(NSString *_Nonnull)mediaId

Parameters

mediaId

The media ID of an uploaded file on the Agora server.

Return Value

An AgoraRtmFileMessage instance.

Discussion

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

Declared In

AgoraRtmKit.h

– createImageMessageByMediaId:

Creates an AgoraRtmImageMessage instance by media ID.

- (AgoraRtmImageMessage *)createImageMessageByMediaId:(NSString *_Nonnull)mediaId

Parameters

mediaId

The media ID of an uploaded image on the Agora server.

Return Value

An AgoraRtmImageMessage instance.

Discussion

  • If you have at hand the media ID of an image on the Agora server, you can call this method to create an AgoraRtmImageMessage instance.
  • If you do not have a media ID, then you must call createFileMessageByUploading to get a corresponding AgoraRtmImageMessage instance by uploading an image to the Agora RTM server.

Declared In

AgoraRtmKit.h

– sendMessage:toPeer:sendMessageOptions:completion:

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

- (void)sendMessage:(AgoraRtmMessage *_Nonnull)message toPeer:(NSString *_Nonnull)peerId sendMessageOptions:(AgoraRtmSendMessageOptions *_Nonnull)options completion:(AgoraRtmSendPeerMessageBlock _Nullable)completionBlock

Parameters

message

The message to be sent. For information about creating a message, see AgoraRtmMessage.

peerId

The 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 peerId cannot be empty, nil, or “null”.

options

Options when sending the message to a peer. See AgoraRtmSendMessageOptions.

completionBlock

AgoraRtmSendPeerMessageBlock returns the result of this method call. See AgoraRtmSendPeerMessageErrorCode for the error codes.

Discussion

This method allows you to send a message to a specified user when the user 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 “”.

Declared In

AgoraRtmKit.h

– createChannelWithId:delegate:

Creates an Agora RTM channel.

- (AgoraRtmChannel *_Nullable)createChannelWithId:(NSString *_Nonnull)channelId delegate:(id<AgoraRtmChannelDelegate> _Nullable)delegate

Parameters

channelId

The unique channel name of the Agora RTM session. The string length must not exceed 64 bytes with the following character scope:

  • 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: “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”

NOTE

A channelId cannot be empty, nil, or “null”.

delegate

AgoraRtmChannelDelegate invokes callbacks to be passed to the app on Agora RTM SDK runtime events.

Return Value

  • An AgoraRtmChannel instance if this method call succeeds. 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.
  • nil if this method call fails. Possible reasons: The @p channelId is invalid or you have joined the maximum number of channels..

Discussion

NOTE

You can create multiple AgoraRtmChannel instances in an AgoraRtmKit instance. But you can only join a maximum of 20 channels at the same time. As a good practice, Agora recommends calling the destroyChannelWithId method to release all resources of an RTM channel that you no longer use.

Declared In

AgoraRtmKit.h

– destroyChannelWithId:

Destroys a specified local AgoraRtmChannel instance.

- (BOOL)destroyChannelWithId:(NSString *_Nonnull)channelId

Parameters

channelId

The channel ID of the channel to be destroyed.

Discussion

NOTE

Do not call this method in any of your callbacks.

Declared In

AgoraRtmKit.h

– getRtmCallKit

Gets the AgoraRtmCallKit instance.

- (AgoraRtmCallKit *_Nullable)getRtmCallKit

Return Value

The AgoraRtmCallKit instance.

Declared In

AgoraRtmKit.h

– queryPeersOnlineStatus:completion:

Queries the online status of the specified users.

- (void)queryPeersOnlineStatus:(NSArray<NSString*> *_Nonnull)peerIds completion:(AgoraRtmQueryPeersOnlineBlock _Nullable)completionBlock

Parameters

peerIds

User IDs of the specified users.

completionBlock

AgoraRtmQueryPeersOnlineBlock returns the result of this method call.

Discussion

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

Declared In

AgoraRtmKit.h

– setLocalUserAttributes:completion:

Substitutes the local user’s attributes with new ones.

- (void)setLocalUserAttributes:(NSArray<AgoraRtmAttribute*> *_Nullable)attributes completion:(AgoraRtmSetLocalUserAttributesBlock _Nullable)completionBlock

Parameters

attributes

The new attributes. See AgoraRtmAttribute.

completionBlock

AgoraRtmSetLocalUserAttributesBlock returns the result of this method call.

Discussion

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

Declared In

AgoraRtmKit.h

– addOrUpdateLocalUserAttributes:completion:

Adds or updates the local user’s attributes.

- (void)addOrUpdateLocalUserAttributes:(NSArray<AgoraRtmAttribute*> *_Nullable)attributes completion:(AgoraRtmAddOrUpdateLocalUserAttributesBlock _Nullable)completionBlock

Parameters

attributes

The attrubutes to be added or updated. See AgoraRtmAttribute

completionBlock

AgoraRtmAddOrUpdateLocalUserAttributesBlock returns the result of this method call.

Discussion

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

This method updates the local user’s attributes if it finds that the attributes has/have the same keys, or adds attributes to the local user if it does not.

Declared In

AgoraRtmKit.h

– deleteLocalUserAttributesByKeys:completion:

Deletes the local user’s attributes using attribute keys.

- (void)deleteLocalUserAttributesByKeys:(NSArray<NSString*> *_Nullable)attributeKeys completion:(AgoraRtmDeleteLocalUserAttributesBlock _Nullable)completionBlock

Parameters

attributeKeys

An array of the attribute keys to be deleted.

completionBlock

AgoraRtmDeleteLocalUserAttributesBlock returns the result of this method call.

Discussion

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

Declared In

AgoraRtmKit.h

– clearLocalUserAttributesWithCompletion:

Clears all attributes of the local user.

- (void)clearLocalUserAttributesWithCompletion:(AgoraRtmClearLocalUserAttributesBlock _Nullable)completionBlock

Parameters

completionBlock

AgoraRtmClearLocalUserAttributesBlock returns the result of this method call.

Discussion

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

Declared In

AgoraRtmKit.h

– getUserAllAttributes:completion:

Gets all attributes of a specified user.

- (void)getUserAllAttributes:(NSString *)userId completion:(AgoraRtmGetUserAttributesBlock _Nullable)completionBlock

Parameters

userId

The user ID of the specified user.

completionBlock

AgoraRtmGetUserAttributesBlock returns the result of this method call.

Discussion

For getUserAttributes and getUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Declared In

AgoraRtmKit.h

– getUserAttributes:ByKeys:completion:

Gets the attributes of a specified user using attribute keys.

- (void)getUserAttributes:(NSString *)userId ByKeys:(NSArray<NSString*> *_Nullable)attributeKeys completion:(AgoraRtmGetUserAttributesBlock _Nullable)completionBlock

Parameters

userId

The user ID of the specified user.

attributeKeys

An array of the attribute keys.

completionBlock

AgoraRtmGetUserAttributesBlock returns the result of this method call.

Discussion

For getUserAttributes and getUserAttributesByKeys taken together, the call frequency limit is 40 queries every five seconds.

Declared In

AgoraRtmKit.h

– getChannelMemberCount:completion:

Gets the member count of specified channels.

- (void)getChannelMemberCount:(NSArray<NSString*> *_Nonnull)channelIds completion:(AgoraRtmChannelMemberCountBlock _Nullable)completionBlock

Parameters

channelIds

An array of the specified channel IDs.

completionBlock

AgoraRtmChannelMemberCountBlock returns the result of this method call.

Discussion

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.

Declared In

AgoraRtmKit.h

– setChannel:Attributes:Options:completion:

Resets the attributes of a specified channel.

- (void)setChannel:(NSString *_Nonnull)channelId Attributes:(NSArray<AgoraRtmChannelAttribute*> *_Nullable)attributes Options:(AgoraRtmChannelAttributeOptions *_Nonnull)options completion:(AgoraRtmSetChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

attributes

An array of the attributes. See AgoraRtmChannelAttribute.

options

Options for this attribute operation. See AgoraRtmChannelAttributeOptions.

completionBlock

AgoraRtmSetLocalUserAttributesBlock returns the result of this method call.

Discussion

Declared In

AgoraRtmKit.h

– addOrUpdateChannel:Attributes:Options:completion:

Adds or updates the attributes of a specified channel.

- (void)addOrUpdateChannel:(NSString *_Nonnull)channelId Attributes:(NSArray<AgoraRtmChannelAttribute*> *_Nullable)attributes Options:(AgoraRtmChannelAttributeOptions *_Nonnull)options completion:(AgoraRtmAddOrUpdateChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

attributes

An array of the attributes. See AgoraRtmChannelAttribute.

options

Options for this attribute operation. See AgoraRtmChannelAttributeOptions.

completionBlock

AgoraRtmAddOrUpdateLocalUserAttributesBlock returns the result of this method call.

Discussion

This method updates the specified channel’s attributes if it finds that the attributes has/have the same keys, or adds attributes to the channel if it does not.

Declared In

AgoraRtmKit.h

– deleteChannel:AttributesByKeys:Options:completion:

Deletes the attributes of a specified channel by attribute keys.

- (void)deleteChannel:(NSString *_Nonnull)channelId AttributesByKeys:(NSArray<NSString*> *_Nullable)attributeKeys Options:(AgoraRtmChannelAttributeOptions *_Nonnull)options completion:(AgoraRtmDeleteChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

attributeKeys

An array of the attribute keys.

options

Options for this attribute operation. See AgoraRtmChannelAttributeOptions.

completionBlock

AgoraRtmDeleteLocalUserAttributesBlock returns the result of this method call.

Discussion

Declared In

AgoraRtmKit.h

– clearChannel:Options:AttributesWithCompletion:

Clears all attributes of a specified channel.

- (void)clearChannel:(NSString *_Nonnull)channelId Options:(AgoraRtmChannelAttributeOptions *_Nonnull)options AttributesWithCompletion:(AgoraRtmClearChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

options

Options for this attribute operation. See AgoraRtmChannelAttributeOptions.

completionBlock

AgoraRtmClearLocalUserAttributesBlock returns the result of this method call.

Discussion

  • 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 getChannelAttributes and getChannelAttributesByKeys taken together, the call frequency limit is 10 queries every five seconds.

Declared In

AgoraRtmKit.h

– getChannelAllAttributes:completion:

Gets all attributes of a specified channel.

- (void)getChannelAllAttributes:(NSString *_Nonnull)channelId completion:(AgoraRtmGetChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

completionBlock

AgoraRtmGetUserAttributesBlock returns the result of this method call.

Discussion

Declared In

AgoraRtmKit.h

– getChannelAttributes:ByKeys:completion:

Gets the attributes of a specified channel by attribute keys.

- (void)getChannelAttributes:(NSString *_Nonnull)channelId ByKeys:(NSArray<NSString*> *_Nullable)attributeKeys completion:(AgoraRtmGetChannelAttributesBlock _Nullable)completionBlock

Parameters

channelId

The ID of the specified channel.

attributeKeys

An array of the attribute keys.

completionBlock

AgoraRtmGetUserAttributesBlock returns the result of this method call.

Discussion

Declared In

AgoraRtmKit.h

– subscribePeersOnlineStatus:completion:

Subscribes to the online status of the specified users.

- (void)subscribePeersOnlineStatus:(NSArray<NSString*> *_Nonnull)peerIds completion:(AgoraRtmSubscriptionRequestBlock _Nullable)completionBlock

Parameters

peerIds

User IDs of the specified users.

completionBlock

AgoraRtmSubscriptionRequestBlock returns the result of this method call.

Discussion

  • When the method call succeeds, the SDK returns the PeersOnlineStatusChanged 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 PeersOnlineStatusChanged 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 PeersOnlineStatusChanged 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.

Declared In

AgoraRtmKit.h

– unsubscribePeersOnlineStatus:completion:

Unsubscribes from the online status of the specified users.

- (void)unsubscribePeersOnlineStatus:(NSArray<NSString*> *_Nonnull)peerIds completion:(AgoraRtmSubscriptionRequestBlock _Nullable)completionBlock

Parameters

peerIds

User IDs of the specified users.

completionBlock

AgoraRtmUnsubscriptionRequestBlock returns the result of this method call.

Declared In

AgoraRtmKit.h

– queryPeersBySubscriptionOption:completion:

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

- (void)queryPeersBySubscriptionOption:(AgoraRtmPeerSubscriptionOptions)option completion:(AgoraRtmQueryPeersBySubscriptionOptionBlock _Nullable)completionBlock

Parameters

option

The status type, to which you have subscribed. See AgoraRtmPeerSubscriptionOptions.

completionBlock

AgoraRtmQueryPeersBySubscriptionOptionBlock returns the result of this method call.

Declared In

AgoraRtmKit.h

– setParameters:

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

- (int)setParameters:(NSString *_Nonnull)parameters

Parameters

parameters

SDK options in the JSON format. @return - 0: Success. - ≠0: Failure.

Discussion

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.

Declared In

AgoraRtmKit.h

– setLogFile:

Specifies the default path to the SDK log file.

- (int)setLogFile:(NSString *_Nonnull)logFile

Parameters

logFile

The absolute file path to the log file. The string of the logFile is in UTF-8.

Return Value

  • 0: Success.
  • ≠0: Failure.

Discussion

NOTE

  • Ensure that the directory holding the log file exists and is writable.
  • Ensure that you call this method immediately after calling the initWithAppId method, otherwise the output log may be incomplete.
  • The default log file location is as follows:
    • iOS: App Sandbox/Library/caches/agorartm.log
    • macOS
    • Sandbox enabled: App Sandbox/Library/Logs/agorartm.log, for example /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorartm.log.
    • Sandbox disabled: ~/Library/Logs/agorartm.log.

Declared In

AgoraRtmKit.h

– setLogFileSize:

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

- (int)setLogFileSize:(int)fileSize

Parameters

fileSize

The size of a single log file (KB). The default is 10240 (KB). The value range is [512 KB, 1 GB]. @return - 0: Success. - ≠0: Failure.

Declared In

AgoraRtmKit.h

– setLogFilters:

Sets the output log level of the SDK.

- (int)setLogFilters:(AgoraRtmLogFilter)filter

Parameters

filter

The log filter level. See AgoraRtmLogFilter.

Return Value

  • 0: Success.
  • ≠0: Failure.

Discussion

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.

Declared In

AgoraRtmKit.h

+ getSDKVersion

Gets the version of the Agora RTM SD

+ (NSString *)getSDKVersion

Return Value

The RTM SDK version.

Declared In

AgoraRtmKit.h

+ setRtmServiceContext:

Sets the context of all AgoraRtmKit instances. All AgoraRtmKit instances you create after calling this method match the context.

+ (AgoraRtmSetContextErrorCode)setRtmServiceContext:(AgoraRtmServiceContext *_Nonnull)context

Parameters

context

Context of the AgoraRtmKit instance, including geofencing. See AgoraRtmServiceContext.

Discussion

Note: You must call this method before calling initWithAppId to create an AgoraRtmKit instance or after destroying any existing AgoraRtmKit instance by setting it to nil. Otherwise, this method returns the AgoraRtmSetContextErrorFailure error code.

Declared In

AgoraRtmKit.h