AgoraRtmKit Class Reference

Discussion

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

Discussion

NOTE

• 异地登录后之前的状态（目前主要是加入的频道）不会保留。
• 该方法的调用频率为 2 次每秒。

• 只有在调用本方法成功加入频道后（即收到 AgoraRtmLoginErrorOk 错误码时）才可以调用 RTM 的核心业务逻辑。以下方法除外：

  • createChannelWithId
  • initWithText
  • getRtmCallKit
  • initWithCalleeId

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

• 如果此方法调用成功，本地用户收到 AgoraRtmLoginBlock 和 connectionStateChanged 回调，连接状态变为 AgoraRtmConnectionStateConnected。
• 如果此方法调用失败，本地用户收到 AgoraRtmLoginBlock 和 connectionStateChanged 回调，连接状态变为 AgoraRtmConnectionStateDisconnected。

Discussion

• 如果此方法调用成功，本地用户收到 AgoraRtmLogoutBlock 和 connectionStateChanged 回调，连接状态变为 AgoraRtmConnectionStateDisconnected。
• 如果此方法调用失败，本地用户收到 AgoraRtmLoginBlock 回调。

Discussion

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

Discussion

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

• 如果此方法调用成功，
  • 本地用户收到 AgoraRtmSendPeerMessageBlock 回调。
  • 对端用户收到 messageReceived 回调。
• 如果此方法调用失败，本地用户收到 AgoraRtmSendPeerMessageBlock 回调和错误码。

Discussion

NOTE

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

Discussion

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

NOTE

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

Discussion

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

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

NOTE

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

Discussion

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

Discussion

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

Discussion

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

Discussion

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

Discussion

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

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

• 如果此方法调用成功，
• 本地用户收到 AgoraRtmSendPeerMessageBlock 回调。
• 对端用户收到 messageReceived 回调。
• 如果此方法调用失败，本地用户收到 AgoraRtmSendPeerMessageBlock 回调和错误码。

Discussion

NOTE

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

Discussion

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

Discussion

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

Discussion

setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ，和 clearLocalUserAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ，和 clearLocalUserAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

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

Discussion

setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ，和 clearLocalUserAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

setLocalUserAttributes 、 addOrUpdateLocalUserAttributes 、 deleteLocalUserAttributesByKeys ，和 clearLocalUserAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

getUserAttributes 和 getUserAttributesByKeys 一并计算在内：调用频率上限为每 5 秒 40 次。

Discussion

getUserAttributes 和 getUserAttributesByKeys 一并计算在内：调用频率上限为每 5 秒 40 次。

Discussion

NOTE

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

Discussion

• 你无需加入指定频道即可为该频道设置频道属性。
• 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
• 如果存在多个用户有权限修改频道属性，那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
• setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

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

NOTE

• 你无需加入指定频道即可为该频道更新频道属性。
• 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
• 如果存在多个用户有权限修改频道属性，那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
• setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

• 你无需加入指定频道即可删除该频道的属性。
• 当某频道处于空频道状态（无人状态）数分钟后，该频道的频道属性将被清空。
• 如果存在多个用户有权限修改频道属性，那么我们建议在修改频道属性前先通过调用 getChannelAttributes 方法更新本地频道属性缓存。
• setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

• 你无需加入指定频道即可清空该频道的属性。
• setChannelAttributes 、 addOrUpdateChannelAttributes 、 deleteChannelAttributesByKeys ，和 clearChannelAttributes 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

• 你无需加入指定频道即可查询该频道的属性。
• getChannelAllAttributes 和 getChannelAttributesByKeys 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

• 你无需加入指定频道即可查询该频道的属性。
• getChannelAllAttributes 和 getChannelAttributesByKeys 一并计算在内：调用频率上限为每 5 秒 10 次。

Discussion

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

NOTE

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

Discussion

NOTE

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

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。

Discussion

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

Discussion