AgoraRtmKit Class Reference
Inherits from | NSObject |
---|---|
Declared in | AgoraRtmKit.h |
agoraRtmDelegate
AgoraRtmDelegate 接口类向 App 发送回调通知,上报运行时的事件。
@property (atomic, weak, nullable) id<AgoraRtmDelegate> agoraRtmDelegate
Declared In
AgoraRtmKit.h
channels
DEPRECATED 本地用户频道相关属性。已废弃。
@property (nonatomic, readonly, nullable) NSMutableDictionary<NSString*AgoraRtmChannel*> *channels
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 系统的动态密钥。开启动态鉴权后可用。集成及测试阶段请将 |
---|---|
userId |
登录 Agora RTM 系统的用户 ID。 以下为支持的字符集范围:
NOTE 请不要将 |
completionBlock |
AgoraRtmLoginBlock 回调返回登录结果。错误码详见 AgoraRtmLoginErrorCode。 |
Discussion
NOTE
异地登录后之前的状态(目前主要是加入的频道)不会保留。
该方法的调用频率为 2 次每秒。
只有在调用本方法成功加入频道后(即收到
AgoraRtmLoginErrorOk
错误码时)才可以调用 RTM 的核心业务逻辑。以下方法除外:
App 调用此方法后,本地用户收到 connectionStateChanged 回调,连接状态变为 AgoraRtmConnectionStateConnecting
。
如果此方法调用成功,本地用户收到 AgoraRtmLoginBlock 和 connectionStateChanged 回调,连接状态变为
AgoraRtmConnectionStateConnected
。如果此方法调用失败,本地用户收到 AgoraRtmLoginBlock 和 connectionStateChanged 回调,连接状态变为
AgoraRtmConnectionStateDisconnected
。
Declared In
AgoraRtmKit.h
– logoutWithCompletion:
登出 Agora RTM 系统。
- (void)logoutWithCompletion:(AgoraRtmLogoutBlock _Nullable)completionBlock
Parameters
completionBlock |
AgoraRtmLogoutBlock 回调返回登出结果。错误码详见 AgoraRtmLogoutErrorCode。 |
---|
Discussion
如果此方法调用成功,本地用户收到 AgoraRtmLogoutBlock 和 connectionStateChanged 回调,连接状态变为
AgoraRtmConnectionStateDisconnected
。如果此方法调用失败,本地用户收到 AgoraRtmLoginBlock 回调。
Declared In
AgoraRtmKit.h
– renewToken:completion:
更新当前的 RTM Token。
- (void)renewToken:(NSString *_Nonnull)token completion:(AgoraRtmRenewTokenBlock _Nullable)completionBlock
Parameters
token |
新的 RTM Token。 |
---|---|
completionBlock |
AgoraRtmRenewTokenBlock 回调返回更新当前 Token 的结果。
|
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 方法发送点对点消息或点对点的离线消息。
如果此方法调用成功,
本地用户收到 AgoraRtmSendPeerMessageBlock 回调。
对端用户收到 messageReceived 回调。
如果此方法调用失败,本地用户收到 AgoraRtmSendPeerMessageBlock 回调和错误码。
NOTE
消息(频道消息和点对点消息一并计算在内)的最高发送频率为每 3 秒 180 次。
Declared In
AgoraRtmKit.h
– downloadMediaToMemory:withRequest:completion:
通过 media ID 从 Agora 服务器下载文件或图片至本地内存。
- (void)downloadMediaToMemory:(NSString *_Nonnull)mediaId withRequest:(long long *)requestId completion:(AgoraRtmDownloadMediaToMemoryBlock _Nullable)completionBlock
Parameters
mediaId |
服务器上待下载的文件或图片对应的 media ID。 |
---|---|
requestId |
标识本次下载请求的唯一 ID。 |
completionBlock |
AgoraRtmDownloadMediaToMemoryBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmDownloadMediaErrorCode。 |
Discussion
NOTE
该方法适用于需要快速读取下载文件或图片的场景。
SDK 会在 AgoraRtmDownloadMediaToMemoryBlock 回调结束后立即释放下载的文件或图片。
Declared In
AgoraRtmKit.h
– downloadMedia:toFile:withRequest:completion:
通过 media ID 从 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。 |
Declared In
AgoraRtmKit.h
– createFileMessageByUploading:withRequest:completion:
上传一个文件到 Agora 服务器以获取一个相应的 AgoraRtmFileMessage 文件消息实例。
- (void)createFileMessageByUploading:(NSString *_Nonnull)filePath withRequest:(long long *)requestId completion:(AgoraRtmUploadFileMediaBlock _Nullable)completionBlock
Parameters
filePath |
待上传文件在本地的完整路径。文件路径必须为 UTF-8 编码格式。 |
---|---|
requestId |
标识本次上传请求的唯一 ID。 |
completionBlock |
AgoraRtmUploadFileMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmUploadMediaErrorCode。 |
Discussion
SDK 会通过 AgoraRtmUploadFileMediaBlock 回调返回方法的调用结果。如果方法调用成功,该回调返回一个对应的 AgoraRtmFileMessage 实例。
NOTE
如果你已经有了一个保存在 Agora 服务器上的文件对应的 media ID,你可以调用 createFileMessageByMediaId 创建一个 AgoraRtmFileMessage 实例。
如需取消一个正在进行的上传任务,请调用 cancelMediaUpload 方法。
Declared In
AgoraRtmKit.h
– createImageMessageByUploading:withRequest:completion:
上传一个图片到 Agora 服务器以获取一个相应的 AgoraRtmImageMessage 图片消息实例。
- (void)createImageMessageByUploading:(NSString *_Nonnull)filePath withRequest:(long long *)requestId completion:(AgoraRtmUploadImageMediaBlock _Nullable)completionBlock
Parameters
filePath |
待上传图片在本地的完整路径。文件路径必须为 UTF-8 编码格式。 |
---|---|
requestId |
标识本次上传请求的唯一 ID。 |
completionBlock |
AgoraRtmUploadImageMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmUploadMediaErrorCode。 |
Discussion
SDK 会通过 AgoraRtmUploadImageMediaBlock 回调返回方法的调用结果。如果方法调用成功,该回调返回一个对应的 AgoraRtmImageMessage 实例。
如果上传图片为 JPEG、JPG、BMP,或 PNG 格式,SDK 会自动计算上传图片的宽和高。你可以从 AgoraRtmImageMessage 实例获取计算出的宽和高。
如果上传图片为其他格式,你需要在 AgoraRtmImageMessage 实例内自行设置图片的宽和高。
NOTE
如果你已经有了一个保存在 Agora 服务器上的图片对应的 media ID,你可以调用 createImageMessageByMediaId 创建一个 AgoraRtmImageMessage 实例。
如需取消一个正在进行的上传任务,请调用 cancelMediaUpload 方法。
Declared In
AgoraRtmKit.h
– cancelMediaDownload:completion:
通过 request ID 取消一个正在进行中的文件或图片下载任务。
- (void)cancelMediaDownload:(long long)requestId completion:(AgoraRtmCancelMediaBlock _Nullable)completionBlock
Parameters
requestId |
标识本次下载请求的唯一 ID。 |
---|---|
completionBlock |
AgoraRtmCancelMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmCancelMediaErrorCode。 |
Discussion
NOTE
你只能取消一个正在进行中的下载任务。下载任务完成后则无法取消下载任务,因为相应的 request ID 已不再有效。
Declared In
AgoraRtmKit.h
– cancelMediaUpload:completion:
通过 request ID 取消一个正在进行中的文件或图片上传任务。
- (void)cancelMediaUpload:(long long)requestId completion:(AgoraRtmCancelMediaBlock _Nullable)completionBlock
Parameters
requestId |
标识本次上传请求的唯一 ID。 |
---|---|
completionBlock |
AgoraRtmCancelMediaBlock 回调返回发送点对点消息的结果。错误码详见 AgoraRtmCancelMediaErrorCode。 |
Discussion
NOTE
你只能取消一个正在进行中的上传任务。上传任务完成后则无法取消上传任务,因为相应的 request ID 已不再有效。
Declared In
AgoraRtmKit.h
– createFileMessageByMediaId:
通过 media ID 创建一个 AgoraRtmFileMessage 实例。
- (AgoraRtmFileMessage *)createFileMessageByMediaId:(NSString *_Nonnull)mediaId
Parameters
mediaId |
已上传到 Agora 服务器的文件的 media ID。 |
---|
Return Value
一个 AgoraRtmFileMessage 实例。
Discussion
如果你已经有了一个保存在 Agora 服务器上的文件对应的 media ID,你可以调用本方法创建一个 AgoraRtmFileMessage 实例。
如果你没有相应的 media ID,那么你必须通过调用 createFileMessageByUploading 方法上传相应的文件到 Agora 服务器来获得一个对应的 AgoraRtmFileMessage 实例。
Declared In
AgoraRtmKit.h
– createImageMessageByMediaId:
通过 media ID 创建一个 AgoraRtmImageMessage 实例。
- (AgoraRtmImageMessage *)createImageMessageByMediaId:(NSString *_Nonnull)mediaId
Parameters
mediaId |
已上传到 Agora 服务器的图片的 media ID。 |
---|
Return Value
一个 AgoraRtmImageMessage 实例。
Discussion
如果你已经有了一个保存在 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。 以下为支持的字符集范围:
NOTE 请不要将 |
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 次。
如果此方法调用成功,
本地用户收到 AgoraRtmSendPeerMessageBlock 回调。
对端用户收到 messageReceived 回调。
如果此方法调用失败,本地用户收到 AgoraRtmSendPeerMessageBlock 回调和错误码。
Declared In
AgoraRtmKit.h
– createChannelWithId:delegate:
创建一个 Agora RTM 频道。
- (AgoraRtmChannel *_Nullable)createChannelWithId:(NSString *_Nonnull)channelId delegate:(id<AgoraRtmChannelDelegate> _Nullable)delegate
Parameters
channelId |
标识 Agora RTM 通话的频道名称。 以下为支持的字符集范围:
|
---|---|
delegate |
AgoraRtmChannelDelegate 接口类向 App 发送回调通知,上报运行时的频道相关事件。 |
Return Value
调用成功:一个 AgoraRtmChannel 实例。如果具有相同
channelId
的频道不存在,此方法会返回已创建的频道实例。如果已经存在具有相同channelId
的频道,此方法会返回已存在的频道实例。调用失败:
nil
。原因可能是channelId
无效或频道数量超过限制。
Discussion
NOTE
一个 AgoraRtmKit 实例中可以创建多个频道,但是同一个用户只能同时加入最多 20 个频道。请在不使用某个频道时,调用 destroyChannelWithId 方法销毁频道实例。
Declared In
AgoraRtmKit.h
– destroyChannelWithId:
释放一个 AgoraRtmChannel 本地频道占用的所有资源。
- (BOOL)destroyChannelWithId:(NSString *)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 回调返回发送点对点消息的结果,
|
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
setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ,和 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
setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
如果属性已存在,该方法更新本地用户的已有属性;
如果属性不存在,该方法增加本地用户的属性。
Declared In
AgoraRtmKit.h
– deleteLocalUserAttributesByKeys:completion:
删除本地用户的指定属性。
- (void)deleteLocalUserAttributesByKeys:(NSArray<NSString*> *_Nullable)attributeKeys completion:(AgoraRtmDeleteLocalUserAttributesBlock _Nullable)completionBlock
Parameters
attributeKeys |
属性名数组。 |
---|---|
completionBlock |
通过 AgoraRtmDeleteLocalUserAttributesBlock 回调返回方法调用的结果。 |
Discussion
setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
Declared In
AgoraRtmKit.h
– clearLocalUserAttributesWithCompletion:
清空本地用户的属性。
- (void)clearLocalUserAttributesWithCompletion:(AgoraRtmClearLocalUserAttributesBlock _Nullable)completionBlock
Parameters
completionBlock |
通过 AgoraRtmClearLocalUserAttributesBlock 回调返回方法调用的结果。 |
---|
Discussion
setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ,和 clearLocalUserAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
Declared In
AgoraRtmKit.h
– getUserAllAttributes:completion:
获取指定用户的全部属性。
- (void)getUserAllAttributes:(NSString *)userId completion:(AgoraRtmGetUserAttributesBlock _Nullable)completionBlock
Parameters
userId |
指定用户的用户 ID。 |
---|---|
completionBlock |
通过 AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。 |
Discussion
getUserAttributes 和 getUserAttributesByKeys 一并计算在内:调用频率上限为每 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
getUserAttributes 和 getUserAttributesByKeys 一并计算在内:调用频率上限为每 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
你无需加入指定频道即可为该频道设置频道属性。
当某频道处于空频道状态(无人状态)数分钟后,该频道的频道属性将被清空。
如果存在多个用户有权限修改频道属性,那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
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
你无需加入指定频道即可为该频道更新频道属性。
当某频道处于空频道状态(无人状态)数分钟后,该频道的频道属性将被清空。
如果存在多个用户有权限修改频道属性,那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
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
你无需加入指定频道即可删除该频道的属性。
当某频道处于空频道状态(无人状态)数分钟后,该频道的频道属性将被清空。
如果存在多个用户有权限修改频道属性,那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
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
你无需加入指定频道即可清空该频道的属性。
setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ,和 clearChannelAttributes 一并计算在内:调用频率上限为每 5 秒 10 次。
Declared In
AgoraRtmKit.h
– getChannelAllAttributes:completion:
查询某指定频道的全部属性。
- (void)getChannelAllAttributes:(NSString *_Nonnull)channelId completion:(AgoraRtmGetChannelAttributesBlock _Nullable)completionBlock
Parameters
channelId |
该指定频道的频道 ID。 |
---|---|
completionBlock |
AgoraRtmGetUserAttributesBlock 回调返回方法调用的结果。 |
Discussion
你无需加入指定频道即可查询该频道的属性。
getChannelAllAttributes 和 getChannelAttributesByKeys 一并计算在内:调用频率上限为每 5 秒 10 次。
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
你无需加入指定频道即可查询该频道的属性。
getChannelAllAttributes 和 getChannelAttributesByKeys 一并计算在内:调用频率上限为每 5 秒 10 次。
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 选项。 |
---|
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。默认值为 |
---|
Return Value
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 |
|
---|
Return Value
Discussion
Note: 你必须在调用 initWithAppId 创建 AgoraRtmKit
实例之前或在销毁所有现存的 AgoraRtmKit
实例(将 AgoraRtmKit
实例设为 nil
)之后调用此方法。 否则,该方法会返回 AgoraRtmSetContextErrorFailure
错误码。
Declared In
AgoraRtmKit.h