Agora RTM C++ API Reference for Linux & Windows

Agora Real-time Messaging (RTM) SDK 提供了稳定可靠、低延时、高并发的全球消息云服务，帮助你快速构建实时场景。

如无特别说明，本页列出的大多数 RTM 核心业务方法都应在调用 login 方法成功收到 onLoginSuccess 回调后调用。

Agora RTM SDK 提供以下功能：

• 登录登出
• 点对点消息
• 查询单个或多个用户的在线状态
• 订阅或退订单个或多个指定用户的在线状态
• 用户属性增删改查
• 频道属性增删改查
• 查询单个或多个频道的成员人数
• 上传和下载文件或图片
• 加入离开频道相关
• 频道消息
• 获取频道成员列表
• 呼叫邀请管理
• 更新当前的 RTM Token
• 日志设置与版本查询
• 定制方法
• 区域限定

登录登出相关

SDK 与 RTM 服务器的连接状态是 RTM 开发过程需要理解的核心概念，详见连接状态管理。

方法	描述
createRtmService	创建并返回一个 IRtmService 实例。
initialize	初始化 IRtmService 实例。
login	登录 Agora RTM 系统。
logout	登出 Agora RTM 系统。
release	释放当前 IRtmService 实例使用的所有资源。

事件	描述
onLoginSuccess	登录 Agora RTM 系统成功回调。
onLoginFailure	登录 Agora RTM 系统失败回调。
onLogout	登出 Agora RTM 系统回调。
onConnectionStateChanged	SDK 与 Agora RTM 系统连接状态发生改变回调。

点对点消息

方法	描述
createMessage	创建并返回一个空文本 IMessage 消息实例。
createMessage	创建并返回一个文本 IMessage 消息实例。
createMessage	创建并返回一个自定义二进制 IMessage 消息实例。
createMessage	创建并返回一个包含文字描述的自定义二进制 IMessage 消息实例。
sendMessageToPeer	向指定用户发送点对点消息或点对点的离线消息。
release	释放当前 IMessage 实例使用的所有资源。

事件	描述
onSendMessageResult	报告 sendMessageToPeer 或 sendMessageToPeer(const char *peerId, const IMessage *message, const SendMessageOptions &options) 方法的调用结果。
onMessageReceivedFromPeer	收到来自对端的点对点消息回调。

查询单个或多个用户的在线状态

方法	描述
queryPeersOnlineStatus	查询单个或多个指定用户的在线状态。

事件	描述
onQueryPeersOnlineStatusResult	报告 queryPeersOnlineStatus 方法的调用结果。

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

方法	描述
subscribePeersOnlineStatus	订阅指定单个或多个用户的在线状态。
unsubscribePeersOnlineStatus	取消订阅指定单个或多个用户的在线状态。
queryPeersBySubscriptionOption	获取某特定内容被订阅的用户列表。

事件	描述
onSubscriptionRequestResult	报告 subscribePeersOnlineStatus 或 unsubscribePeersOnlineStatus 方法的调用结果。
onPeersOnlineStatusChanged	被订阅用户在线状态改变回调。
onQueryPeersBySubscriptionOptionResult	报告 queryPeersBySubscriptionOption 方法的调用结果。

用户属性增删改查

方法	描述
setLocalUserAttributes	全量设置本地用户的属性。
addOrUpdateLocalUserAttributes	添加或更新本地用户的属性。
deleteLocalUserAttributesByKeys	删除本地用户的指定属性。
clearLocalUserAttributes	清空本地用户的属性。
getUserAttributes	查询指定用户的全部属性。
getUserAttributesByKeys	查询指定用户指定属性名的属性。

事件	描述
onSetLocalUserAttributesResult	报告 setLocalUserAttributes 方法的调用结果。
onAddOrUpdateLocalUserAttributesResult	报告 addOrUpdateLocalUserAttributes 方法的调用结果。
onDeleteLocalUserAttributesResult	报告 deleteLocalUserAttributesByKeys 方法的调用结果。
onClearLocalUserAttributesResult	报告 clearLocalUserAttributes 方法的调用结果。
onGetUserAttributesResult	报告 getUserAttributes 方法或 getUserAttributesByKeys 方法的调用结果。

频道属性增删改查

方法	描述
createChannelAttribute	创建并返回一个 IRtmChannelAttribute 实例。
setChannelAttributes	全量设置某指定频道的属性。
addOrUpdateChannelAttributes	添加或更新某指定频道的属性。
deleteChannelAttributesByKeys	删除某指定频道的指定属性。
clearChannelAttributes	清空某指定频道的属性。
getChannelAttributes	查询某指定频道的全部属性。
getChannelAttributesByKeys	查询某指定频道指定属性名的属性。

事件	描述
onSetChannelAttributesResult	报告 setChannelAttributes 方法的调用结果。
onAddOrUpdateChannelAttributesResult	报告 addOrUpdateChannelAttributes 方法的调用结果。
onDeleteChannelAttributesResult	报告 deleteChannelAttributesByKeys 方法的调用结果。
onClearChannelAttributesResult	报告 clearChannelAttributes 方法的调用结果。
onGetChannelAttributesResult	报告 getChannelAttributes 或 getChannelAttributesByKeys 方法的调用结果。

频道属性更新事件	描述
onAttributesUpdated	当频道属性更新时返回当前频道的所有属性。

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

方法	描述
getChannelMemberCount	查询单个或多个频道的成员人数。用户无需加入指定频道即可调用该方法。

事件	描述
onGetChannelMemberCountResult	返回 getChannelMemberCount 方法的调用结果。

上传和下载文件或图片

方法	描述
createFileMessageByUploading	上传一个文件到 Agora 服务器以获取一个相应的 IFileMessage 文件消息实例。
createImageMessageByUploading	上传一个图片到 Agora 服务器以获取一个相应的 IImageMessage 图片消息实例。
cancelMediaUpload	通过 request ID 取消一个正在进行中的文件或图片上传任务。
createFileMessageByMediaId	通过 media ID 创建一个 IFileMessage 实例。
createImageMessageByMediaId	通过 media ID 创建一个 IImageMessage 实例。
downloadMediaToMemory	通过 media ID 从 Agora 服务器下载文件或图片至本地内存。
downloadMediaToFile	通过 media ID 从 Agora 服务器下载文件或图片至本地指定地址。
cancelMediaDownload	通过 request ID 取消一个正在进行中的文件或图片下载任务。

事件	描述
onMediaUploadingProgress	主动回调：上传任务的上传进度回调。
onMediaCancelResult	报告 cancelMediaDownload 或 cancelMediaUpload 方法的调用结果。
onFileMediaUploadResult	报告 createFileMessageByUploading 方法的调用结果。
onImageMediaUploadResult	报告 createImageMessageByUploading 方法的调用结果。
onFileMessageReceivedFromPeer	收到点对点文件消息回调。
onImageMessageReceivedFromPeer	收到点对点图片消息回调。
onFileMessageReceived	收到频道文件消息回调。
onImageMessageReceived	收到频道图片消息回调。
onMediaDownloadingProgress	主动回调：下载任务的下载进度回调。
onMediaCancelResult	报告 cancelMediaDownload 或 cancelMediaUpload 方法的调用结果。
onMediaDownloadToMemoryResult	报告 downloadMediaToMemory 方法的调用结果。
onMediaDownloadToFileResult	报告 downloadMediaToFile 方法的调用结果。

加入离开频道相关

方法	描述
createChannel	创建一个 IChannel 对象。
join	加入频道。
leave	离开频道。
release	释放当前 IChannel 频道实例的所有资源。

事件	描述
onJoinSuccess	成功加入频道回调。
onJoinFailure	加入频道失败回调。
onLeave	报告 leave 方法的调用结果。
onMemberJoined	远端用户加入频道回调。
onMemberLeft	远端用户离开频道回调。
onMemberCountUpdated	频道成员人数更新回调。返回最新频道成员人数。

频道消息

方法	描述
createMessage	创建并返回一个空文本 IMessage 消息实例。
createMessage	创建并返回一个文本 IMessage 消息实例。
createMessage	创建并返回一个自定义二进制 IMessage 消息实例。
createMessage	创建并返回一个包含文字描述的自定义二进制 IMessage 消息实例。
sendMessage	供频道成员向所在频道发送频道消息。
release	释放当前 IMessage 消息实例使用的所有资源。

事件	描述
onSendMessageResult	报告 sendMessage 方法的调用结果。
onMessageReceived	收到频道消息回调。

获取频道成员列表

方法	描述
getMembers	获取当前频道成员列表。

事件	描述
onGetMembers	获取频道成员列表回调。

呼叫邀请管理

• 主叫取消已发送的呼叫邀请的 API 时序图：

• 被叫接受呼叫邀请的 API 时序图：

• 被叫拒绝呼叫邀请的 API 时序图：

呼叫管理器获取与释放方法	描述
getRtmCallManager	获取呼叫邀请管理器。
release	释放当前 IRtmCallManager 实例的所有资源。

供主叫调用的方法	描述
createLocalCallInvitation	供主叫创建、管理一个 ILocalCallInvitation 呼叫邀请对象。
sendLocalInvitation	供主叫向指定用户发送呼叫邀请。
cancelLocalInvitation	供主叫取消一个呼叫邀请。
release	释放当前 ILocalCallInvitation 本地呼叫邀请实例的所有资源。

供被叫调用的方法	描述
acceptRemoteInvitation	供被叫接受一个呼叫邀请。
refuseRemoteInvitation	供被叫拒绝一个呼叫邀请。
release	释放当前 IRemoteCallInvitation 呼叫邀请实例的所有资源。

主叫接收的事件	描述
onLocalInvitationReceivedByPeer	报告给主叫的回调：被叫已收到呼叫邀请。
onLocalInvitationCanceled	报告给主叫的回调：呼叫邀请已被成功取消。
onLocalInvitationAccepted	报告给主叫的回调：被叫已接受呼叫邀请。
onLocalInvitationRefused	报告给主叫的回调：被叫已拒绝呼叫邀请。
onLocalInvitationFailure	报告给主叫的回调：呼叫邀请过程失败。

被叫接收的事件	描述
onRemoteInvitationReceived	报告给被叫的回调：收到一条呼叫邀请。SDK 会同时返回一个 IRemoteCallInvitation 对象供被叫管理。
onRemoteInvitationCanceled	报告给被叫的回调：呼叫邀请已被主叫取消。
onRemoteInvitationAccepted	报告给被叫的回调：已接受呼叫邀请。
onRemoteInvitationRefused	报告给被叫的回调：已拒绝呼叫邀请。
onRemoteInvitationFailure	报告给被叫的回调：呼叫邀请进程失败。

更新 Token

方法	描述
renewToken	更新当前的 RTM Token。

事件	描述
onTokenExpired	（SDK 断线重连时触发）当前使用的 RTM Token 已超过 24 小时的签发有效期。
onRenewTokenResult	报告 renewToken 方法的调用结果。

日志设置与版本查询

• 日志相关操作在调用 createRtmService 方法创建并初始化 IRtmService 实例后即可进行，无需等到调用 login 方法成功。
• 版本查询操作为全局方法，可在创建并初始化 IRtmService 实例前进行。

方法	描述
setLogFile	设定日志文件的默认地址。
setLogFilter	设置日志输出等级。
setLogFileSize	设置 SDK 输出的单个日志文件的大小，单位为 KB。 SDK 设有 2 个大小相同的日志文件。
getRtmSdkVersion	获取 Agora RTM SDK 的版本信息。

定制方法

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

区域限定

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