AgoraRtmKit Class Reference

Inherits from NSObject
Declared in AgoraRtmKit.h

Overview

AgoraRtmKit 类是 Agora RTM SDK 的入口,提供所有可供 App 调用的核心方法。

  agoraRtmDelegate

AgoraRtmDelegate 接口类向 App 发送回调通知,上报运行时的事件。

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

Declared In

AgoraRtmKit.h

  __deprecated

*DEPRECATED** 本地用户频道相关属性。已废弃。

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

Declared In

AgoraRtmKit.h

– initWithAppId:delegate:

创建并初始化一个 AgoraRtmKit 实例。

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

Parameters

appId

如果你的开发包里没有 App ID,请向声网申请一个新的 App ID。

delegate

AgoraRtmDelegate 向 App 发送回调通知,上报 Agora RTM SDK 运行时的事件。

Return Value

  • 调用成功:一个 AgoraRtmKit 实例。
  • 调用失败:nil。可能是因为 appId 的长度不是 32 个字符。

Discussion

Agora RTM SDK 支持多个 AgoraRtmKit 实例。 AgoraRtmKit 类的所有接口函数,除 destroyChannelWithId 方法以外,都是异步调用。

Declared In

AgoraRtmKit.h

– loginByToken:user:completion:

登录 Agora RTM 系统。

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

Parameters

token

用于登录 Agora RTM 系统的动态密钥。开启动态鉴权后可用。集成及测试阶段请将 token 设置为 nil

userId

登录 Agora RTM 系统的用户 ID。 userId 必须为不超过 64 字节的字符串。

以下为支持的字符集范围:

  • 26个小写英文字母 a-z
  • 26个大写英文字母 A-Z
  • 10个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”

NOTE

请不要将 userId 设为空、 nil 或 “null"。

completionBlock

AgoraRtmLoginBlock 回调返回登录结果。错误码详见 AgoraRtmLoginErrorCode。

Discussion

NOTE

  • 异地登录后之前的状态(目前主要是加入的频道)不会保留。
  • 该方法的调用频率为 2 次每秒。
  • 只有在调用本方法成功加入频道后(即收到 AgoraRtmLoginErrorOk 错误码时)才可以调用 RTM 的核心业务逻辑。以下方法除外:

App 调用此方法后,本地用户收到 connectionStateChanged 回调,连接状态变为 AgoraRtmConnectionStateConnecting

Declared In

AgoraRtmKit.h

– logoutWithCompletion:

登出 Agora RTM 系统。

- (void)logoutWithCompletion:(AgoraRtmLogoutBlock _Nullable)completionBlock

Parameters

completionBlock

AgoraRtmLogoutBlock 回调返回登出结果。错误码详见 AgoraRtmLogoutErrorCode。

Discussion

Declared In

AgoraRtmKit.h

– renewToken:completion:

更新 SDK 的 RTM Token。

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

Parameters

token

新的 RTM Token。你需要自行生成 RTM Token。参考《生成 RTM Token》。

completionBlock

AgoraRtmRenewTokenBlock 回调返回更新当前 Token 的结果。

  • token: 新的 RTM Token。
  • errorCode: 错误码。详见 AgoraRtmRenewTokenErrorCode。

Discussion

在收到 rtmKitTokenDidExpire 回调时你需要调用此方法更新 Token。 AgoraRtmRenewTokenBlock 回调会返回 Token 更新的结果。该方法的调用频率为 2 次每秒。

Declared In

AgoraRtmKit.h

– sendMessage:toPeer:completion:

DEPRECATED 向指定用户发送点对点消息。

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

Parameters

message

消息内容。如何创建消息详见 AgoraRtmMessage。

peerId

消息接收者的用户 ID。

completionBlock

AgoraRtmSendPeerMessageBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmSendPeerMessageErrorCode。

Discussion

我们不推荐使用该方法发送点对点消息。请改用 sendMessage 方法发送点对点消息或点对点的离线消息。

NOTE

消息(频道消息和点对点消息一并计算在内)的最高发送频率为每 3 秒 180 次。

Declared In

AgoraRtmKit.h

– downloadMediaToMemory:withRequest:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

mediaId

服务器上待下载的文件或图片对应的 media ID。

requestId

标识本次下载请求的唯一 ID。

completionBlock

AgoraRtmDownloadMediaToMemoryBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmDownloadMediaErrorCode。

Discussion

通过 media ID 从 Agora 服务器下载文件或图片至本地内存。

NOTE

  • 该方法适用于需要快速读取下载文件或图片的场景。
  • SDK 会在 AgoraRtmDownloadMediaToMemoryBlock 回调结束后立即释放下载的文件或图片。

Declared In

AgoraRtmKit.h

– downloadMedia:toFile:withRequest:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

mediaId

服务器上待下载的文件或图片对应的 media ID。

filePath

下载文件或图片在本地存储的完整路径。文件路径必须为 UTF-8 编码格式。

requestId

标识本次下载请求的唯一 ID。

completionBlock

AgoraRtmDownloadMediaToFileBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmDownloadMediaErrorCode。

Discussion

通过 media ID 从 Agora 服务器下载文件或图片至本地指定地址。

Declared In

AgoraRtmKit.h

– createFileMessageByUploading:withRequest:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

filePath

待上传文件在本地的完整路径。文件路径必须为 UTF-8 编码格式。

requestId

标识本次上传请求的唯一 ID。

completionBlock

AgoraRtmUploadFileMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmUploadMediaErrorCode。

Discussion

上传一个文件到 Agora 服务器以获取一个相应的 AgoraRtmFileMessage 文件消息实例。

SDK 会通过 AgoraRtmUploadFileMediaBlock 回调返回方法的调用结果。如果方法调用成功,该回调返回一个对应的 AgoraRtmFileMessage 实例。

NOTE

  • 如果你已经有了一个保存在 Agora 服务器上的文件对应的 media ID,你可以调用 createFileMessageByMediaId 创建一个 AgoraRtmFileMessage 实例。
  • 如需取消一个正在进行的上传任务,请调用 cancelMediaUpload 方法。

Declared In

AgoraRtmKit.h

– createImageMessageByUploading:withRequest:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

filePath

待上传图片在本地的完整路径。文件路径必须为 UTF-8 编码格式。

requestId

标识本次上传请求的唯一 ID。

completionBlock

AgoraRtmUploadImageMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmUploadMediaErrorCode。

Discussion

上传一个图片到 Agora 服务器以获取一个相应的 AgoraRtmImageMessage 图片消息实例。

SDK 会通过 AgoraRtmUploadImageMediaBlock 回调返回方法的调用结果。如果方法调用成功,该回调返回一个对应的 AgoraRtmImageMessage 实例。

  • 如果上传图片为 JPEG、JPG、BMP,或 PNG 格式,SDK 会自动计算上传图片的宽和高。你可以从 AgoraRtmImageMessage 实例获取计算出的宽和高。
  • 如果上传图片为其他格式,你需要在 AgoraRtmImageMessage 实例内自行设置图片的宽和高。

NOTE

  • 如果你已经有了一个保存在 Agora 服务器上的图片对应的 media ID,你可以调用 createImageMessageByMediaId 创建一个 AgoraRtmImageMessage 实例。
  • 如需取消一个正在进行的上传任务,请调用 cancelMediaUpload 方法。

Declared In

AgoraRtmKit.h

– cancelMediaDownload:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

requestId

标识本次下载请求的唯一 ID。

completionBlock

AgoraRtmCancelMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmCancelMediaErrorCode。

Discussion

通过 request ID 取消一个正在进行中的文件或图片下载任务。

NOTE 你只能取消一个正在进行中的下载任务。下载任务完成后则无法取消下载任务,因为相应的 request ID 已不再有效。

Declared In

AgoraRtmKit.h

– cancelMediaUpload:completion:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

requestId

标识本次上传请求的唯一 ID。

completionBlock

AgoraRtmCancelMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmCancelMediaErrorCode。

Discussion

通过 request ID 取消一个正在进行中的文件或图片上传任务。

NOTE 你只能取消一个正在进行中的上传任务。上传任务完成后则无法取消上传任务,因为相应的 request ID 已不再有效。

Declared In

AgoraRtmKit.h

– createFileMessageByMediaId:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

mediaId

已上传到 Agora 服务器的文件的 media ID。

Return Value

一个 AgoraRtmFileMessage 实例。

Discussion

通过 media ID 创建一个 AgoraRtmFileMessage 实例。

  • 如果你已经有了一个保存在 Agora 服务器上的文件对应的 media ID,你可以调用本方法创建一个 AgoraRtmFileMessage 实例。
  • 如果你没有相应的 media ID,那么你必须通过调用 createFileMessageByUploading 方法上传相应的文件到 Agora 服务器来获得一个对应的 AgoraRtmFileMessage 实例。

Declared In

AgoraRtmKit.h

– createImageMessageByMediaId:

DEPRECATED 该方法自 1.5.0 版本开始正式下线,Agora 建议你不要使用。

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

Parameters

mediaId

已上传到 Agora 服务器的图片的 media ID。

Return Value

一个 AgoraRtmImageMessage 实例。

Discussion

通过 media ID 创建一个 AgoraRtmImageMessage 实例。

  • 如果你已经有了一个保存在 Agora 服务器上的图片对应的 media ID,你可以调用本方法创建一个 AgoraRtmImageMessage 实例。
  • 如果你没有相应的 media ID,那么你必须通过调用 createFileMessageByUploading 方法上传相应的文件到 Agora 服务器来获得一个对应的 AgoraRtmImageMessage 实例。

Declared In

AgoraRtmKit.h

– sendMessage:toPeer:sendMessageOptions:completion:

向指定用户发送点对点消息或点对点的离线消息。

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

Parameters

message

消息内容。如何创建消息详见 AgoraRtmMessage。

peerId

消息接收者的用户 ID。peerId 必须为不超过 64 字节的字符串。

以下为支持的字符集范围:

  • 26个小写英文字母 a-z
  • 26个大写英文字母 A-Z
  • 10个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”

NOTE

请不要将 userId 设为空、 nil 或 “null"。

options

消息发送选项。详见 AgoraRtmSendMessageOptions。

completionBlock

AgoraRtmSendPeerMessageBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmSendPeerMessageErrorCode。

Discussion

该方法允许你向离线用户发送点对点消息。如果指定用户在你发送离线消息时不在线,消息服务器会保存该条消息。请注意,目前我们只为每个接收端保存 200 条离线消息最长七天。当保存的离线消息超出限制时,最老的信息将会被最新的消息替换。

本方法可与老信令 SDK 的 endCall 方法兼容。你只需在用本方法发送文本消息时将消息头设为 AGORA_RTM_ENDCALL_PREFIX_<channelId>_<your additional information> 格式即可。请以 endCall 对应频道的 ID 替换 <channelId>, <your additional information> 为附加文本信息。请注意:附加文本信息中不可使用下划线 “_” ,附加文本信息可以设为空字符串 “"。

NOTE

消息(频道消息和点对点消息一并计算在内)的最高发送频率为每 3 秒 180 次。

Declared In

AgoraRtmKit.h

– createChannelWithId:delegate:

创建一个 Agora RTM 频道。

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

Parameters

channelId

标识 Agora RTM 通话的频道名称。channelId 必须为不超过 64 字节的字符串,不能为空、nil,或设为 “null"。

以下为支持的字符集范围:

  • 26个小写英文字母 a-z
  • 26个大写英文字母 A-Z
  • 10个数字 0-9
  • 空格
  • “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “ {”, “}”, “|”, “~”, “,”
delegate

AgoraRtmChannelDelegate 接口类向 App 发送回调通知,上报运行时的频道相关事件。

Return Value

  • 调用成功:一个 AgoraRtmChannel 实例。如果具有相同 channelId 的频道不存在,此方法会返回已创建的频道实例。如果已经存在具有相同 channelId 的频道,此方法会返回已存在的频道实例。
  • 调用失败:nil。原因可能是 channelId 无效或频道数量超过限制。

Discussion

NOTE

一个 AgoraRtmKit 实例中可以创建多个频道,但是同一个用户只能同时加入最多 20 个频道。请在不使用某个频道时,调用 destroyChannelWithId 方法销毁频道实例。

Declared In

AgoraRtmKit.h

– destroyChannelWithId:

 释放一个 AgoraRtmChannel 本地频道占用的所有资源。

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

Parameters

channelId

待释放的频道实例的 ID。

Discussion

NOTE 请不要在任何回调中调用该方法。

Declared In

AgoraRtmKit.h

– getRtmCallKit

获取一个 AgoraRtmCallKit 实例。

- (AgoraRtmCallKit *_Nullable)getRtmCallKit

Return Value

一个 AgoraRtmCallKit 实例。

Declared In

AgoraRtmKit.h

– queryPeersOnlineStatus:completion:

查询指定用户的在线状态。

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

Parameters

peerIds

用户 ID 列表。

completionBlock

通过 AgoraRtmQueryPeersOnlineBlock 回调返回发送点对点消息的结果,

  • peerOnlineStatus: 用户在线状态列表。单元结构详见 AgoraRtmPeerOnlineStatus。
  • errorCode: 错误码。详见 AgoraRtmQueryPeersOnlineErrorCode。

Discussion

  • 在线:用户已登录到 Agora RTM 系统。
  • 不在线:用户已登出 Agora RTM 系统或因其他原因与 Agora RTM 系统断开连接。

Declared In

AgoraRtmKit.h

– setLocalUserAttributes:completion:

全量设置本地用户的属性。

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

Parameters

attributes

待设置的属性。详见 AgoraRtmAttribute。

completionBlock

通过 AgoraRtmSetLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

setLocalUserAttributesaddOrUpdateLocalUserAttributesdeleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。

Declared In

AgoraRtmKit.h

– addOrUpdateLocalUserAttributes:completion:

添加或更新本地用户的属性。

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

Parameters

attributes

待增加或更新的属性。详见 AgoraRtmAttribute。

completionBlock

通过 AgoraRtmAddOrUpdateLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

setLocalUserAttributesaddOrUpdateLocalUserAttributesdeleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。

  • 如果属性已存在,该方法更新本地用户的已有属性;
  • 如果属性不存在,该方法增加本地用户的属性。

Declared In

AgoraRtmKit.h

– deleteLocalUserAttributesByKeys:completion:

删除本地用户的指定属性。

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

Parameters

attributeKeys

属性名数组。

completionBlock

通过 AgoraRtmDeleteLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

setLocalUserAttributesaddOrUpdateLocalUserAttributesdeleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。

Declared In

AgoraRtmKit.h

– clearLocalUserAttributesWithCompletion:

清空本地用户的属性。

- (void)clearLocalUserAttributesWithCompletion:(AgoraRtmClearLocalUserAttributesBlock _Nullable)completionBlock

Parameters

completionBlock

通过 AgoraRtmClearLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

setLocalUserAttributesaddOrUpdateLocalUserAttributesdeleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。

Declared In

AgoraRtmKit.h

– getUserAllAttributes:completion:

获取指定用户的全部属性。

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

Parameters

userId

指定用户的用户 ID。

completionBlock

通过 AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。

Discussion

getUserAttributesgetUserAttributesByKeys 一并计算在内:调用频率上限为每 5 秒 40 次。

Declared In

AgoraRtmKit.h

– getUserAttributes:ByKeys:completion:

获取指定用户指定属性名的属性。

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

Parameters

userId

指定用户的用户 ID。

attributeKeys

属性名数组。

completionBlock

通过 AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。

Discussion

getUserAttributesgetUserAttributesByKeys 一并计算在内:调用频率上限为每 5 秒 40 次。

Declared In

AgoraRtmKit.h

– getChannelMemberCount:completion:

查询单个或多个频道的成员人数。

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

Parameters

channelIds

指定频道名数组。

completionBlock

AgoraRtmChannelMemberCountBlock 回调返回方法调用的结果。

Discussion

NOTE

  • 该方法的调用频率上限为每秒 1 次。
  • 不支持一次查询超过 32 个频道的成员人数。

Declared In

AgoraRtmKit.h

– setChannel:Attributes:Options:completion:

全量设置某指定频道的属性。

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

Parameters

channelId

该指定频道的频道 ID。

attributes

频道属性数组。详见 AgoraRtmChannelAttribute。

options

频道属性操作选项。详见 AgoraRtmChannelAttributeOptions。

completionBlock

AgoraRtmSetLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

Declared In

AgoraRtmKit.h

– addOrUpdateChannel:Attributes:Options:completion:

添加或更新某指定频道的属性。

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

Parameters

channelId

该指定频道的频道 ID。

attributes

频道属性数组。详见 AgoraRtmChannelAttribute。

options

频道属性操作选项。详见 AgoraRtmChannelAttributeOptions。

completionBlock

AgoraRtmAddOrUpdateLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

  • 如果属性已存在,该方法更新该频道的已有属性;
  • 如果属性不存在,该方法增加该频道的属性。

NOTE

Declared In

AgoraRtmKit.h

– deleteChannel:AttributesByKeys:Options:completion:

删除某指定频道的指定属性。

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

Parameters

channelId

该指定频道的频道 ID。

attributeKeys

频道属性名数组。

options

频道属性操作选项。详见 AgoraRtmChannelAttributeOptions。

completionBlock

AgoraRtmDeleteLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

Declared In

AgoraRtmKit.h

– clearChannel:Options:AttributesWithCompletion:

清空某指定频道的属性。

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

Parameters

channelId

该指定频道的频道 ID。

options

频道属性操作选项。详见 AgoraRtmChannelAttributeOptions。

completionBlock

AgoraRtmClearLocalUserAttributesBlock 回调返回方法调用的结果。

Discussion

Declared In

AgoraRtmKit.h

– getChannelAllAttributes:completion:

查询某指定频道的全部属性。

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

Parameters

channelId

该指定频道的频道 ID。

completionBlock

AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。

Discussion

Declared In

AgoraRtmKit.h

– getChannelAttributes:ByKeys:completion:

查询某指定频道指定属性名的属性。

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

Parameters

channelId

该指定频道的频道 ID。

attributeKeys

频道属性名数组。

completionBlock

AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。

Discussion

Declared In

AgoraRtmKit.h

– subscribePeersOnlineStatus:completion:

订阅指定单个或多个用户的在线状态。

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

Parameters

peerIds

用户 ID 列表。

completionBlock

AgoraRtmSubscriptionRequestBlock 回调返回方法调用的结果。

Discussion

  • 首次订阅成功后,SDK 会通过 PeersOnlineStatusChanged 回调返回被订阅用户在线状态。
  • 每当被订阅用户在线状态发生变化时,SDK 都会通过 PeersOnlineStatusChanged 回调通知订阅方。
  • 如果 SDK 在断线重连过程中有被订阅用户的在线状态发生改变,SDK 会在重连成功时通过 PeersOnlineStatusChanged 回调通知订阅方。

NOTE

  • 用户登出 Agora RTM 系统后,所有之前的订阅内容都会被清空;重新登录后,如需保留之前订阅内容则需重新订阅。
  • SDK 会在网络连接中断时进入断线重连状态。重连成功时 SDK 会自动重新订阅之前订阅用户,无需人为干预。

Declared In

AgoraRtmKit.h

– unsubscribePeersOnlineStatus:completion:

退订指定单个或多个用户的在线状态。

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

Parameters

peerIds

用户 ID 列表。

completionBlock

AgoraRtmUnsubscriptionRequestBlock 回调返回方法调用的结果。

Declared In

AgoraRtmKit.h

– queryPeersBySubscriptionOption:completion:

获取某特定内容被订阅的用户列表。

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

Parameters

option

被订阅的状态类型。详见 AgoraRtmPeerSubscriptionOptions。

completionBlock

AgoraRtmQueryPeersBySubscriptionOptionBlock 回调返回方法调用的结果。

Declared In

AgoraRtmKit.h

– setParameters:

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

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

Parameters

parameters

JSON 格式的 SDK 选项。 @return - 0: 方法调用成功。 - ≠0: 方法调用失败。

Discussion

NOTE

JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。详情请联系 support@agora.io

Declared In

AgoraRtmKit.h

– setLogFile:

设定日志文件的默认地址。

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

Parameters

logFile

日志文件的绝对路径。编码格式为 UTF-8。

Return Value

  • 0: 方法调用成功;
  • ≠0: 方法调用失败。

Discussion

NOTE

  • 请确保指定的路径可写。
  • 如需调用本方法,请在调用 initWithAppId 方法创建并初始化 AgoraRtmKit 实例后立即调用,否则会造成输出日志不完整。
  • 日志文件的默认地址如下:
    • iOS: App Sandbox/Library/caches/agorartm.log
    • macOS
      • 开启沙盒: App Sandbox/Library/Logs/agorartm.log。如: /Users/<username>/Library/Containers/<App Bundle Identifier>/Data/Library/Logs/agorartm.log
      • 关闭沙盒: ~/Library/Logs/agorartm.log

Declared In

AgoraRtmKit.h

– setLogFileSize:

设置 SDK 输出的单个日志文件的大小,单位为 KB。 SDK 设有 2 个大小相同的日志文件。

- (int)setLogFileSize:(int)fileSize

Parameters

fileSize

SDK 输出的单个日志文件的大小,单位为 KB。默认值为 10240 (KB)。取值范围为 [512 KB, 1 GB]。 @return - 0: 方法调用成功; - ≠0: 方法调用失败。

Declared In

AgoraRtmKit.h

– setLogFilters:

设置日志输出等级。

- (int)setLogFilters:(AgoraRtmLogFilter)filter

Parameters

filter

日志输出等级。详见 AgoraRtmLogFilter。

Return Value

  • 0: 方法调用成功;
  • ≠0: 方法调用失败。

Discussion

设置 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING 和 INFO。选择一个级别,你就可以看到在该级别之前所有级别的日志信息。例如,你选择 WARNING 级别,就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

Declared In

AgoraRtmKit.h

+ getSDKVersion

获取 Agora RTM SDK 的版本信息。

+ (NSString *)getSDKVersion

Return Value

Agora RTM SDK 的版本信息。

Declared In

AgoraRtmKit.h

+ setRtmServiceContext:

设置所有 AgoraRtmKit 实例的上下文。你在成功调用此方法之后创建的所有 AgoraRtmKit 实例都符合此方法设置的上下文。

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

Parameters

context

AgoraRtmKit 实例的上下文,包括区域限定和云代理设置。详见 AgoraRtmServiceContext

Return Value

AgoraRtmSetContextErrorCode

Discussion

Note: 你必须在调用 initWithAppId 创建 AgoraRtmKit 实例之前或在销毁所有现存的 AgoraRtmKit 实例(将 AgoraRtmKit 实例设为 nil)之后调用此方法。 否则,该方法会返回 AgoraRtmSetContextErrorFailure 错误码。

Declared In

AgoraRtmKit.h