快速入门

最近更新时间：2022-09-20 05:17:40

Android
Flutter
iOS
uniapp
Web
Windows
小程序
开发环境要求
快速集成
获取应用的AppID
获取 SDK
导入 SDK
操作流程
初始化SDK
登录
点对点消息
频道消息
开发注意事项

本文主要介绍如何将 anyRTC RTM Windows SDK 实时消息集成到你的项目中以及相关注意事项。

开发环境要求

  • 一个有效的 anyRTC 开发者账号。
  • Windows Visual Studio 2017 或以上版本
  • 运行在 Windows 7 及以上版本的 Windows 设备。

快速集成

本小节介绍如何获取 AppID 以及如何快速集成到项目中。

获取应用的AppID

  • 1. 创建项目

    首先我们需要在 anyRTC 用户控制台创建一个「项目」。

  • 2. 获取 APP ID

    获取项目的「APP ID」。

获取 SDK

快速集成包括获取 SDK 和引入 SDK 。

导入 SDK

参考以下步骤创建一个 Windows 项目。

创建 Windows 项目
  1. 打开 Microsoft Visual Studio 并点击新建项目。
  2. 进入新建项目窗口，选择项目类型为 MFC 应用程序，输入项目名称，选择项目存储路径，并点击确认。
  3. 进入MFC 应用程序窗口，选择应用程序类型为基于对话框，并点击完成。

1. 配置项目文件

  • 根据应用场景，从 SDK 下载获取最新 SDK，解压并打开。

  • 打开已下载的 SDK 文件，并将其中的 sdk 文件夹复制到你的项目文件夹下。

2. 配置项目属性

在解决方案资源管理器窗口中，右击项目名称并点击属性进行以下配置，配置完成后点击确定。

  • 进入 C/C++ > 常规 > 附加包含目录菜单，点击编辑，并在弹出窗口中输入 $(SolutionDir)include。

  • 进入链接器 > 常规 > 附加库目录菜单，点击编辑，并在弹出窗口中输入 $(SolutionDir)。

  • 进入链接器 > 输入 > 附加依赖项菜单，点击编辑，并在弹出窗口中输入 ARtmKit.lib。

操作流程

初始化SDK

  1. 根据需求继承实现 ar::rtm::IRtmServiceEventHandler ar::rtm::IChannelEventHandler。

  2. 创建 ar::rtm::IRtmService ar::rtm::IRtmServiceEventHandler ar::rtm::IChannelEventHandler 实例 rtmInstance_ 初始化。

#include "IArRtmService.h"

std::unique_ptr<ar::rtm::IRtmServiceEventHandler> RtmEventCallback_;
std::unique_ptr<ar::rtm::IChannelEventHandler> channelEventCallback_;
std::shared_ptr<ar::rtm::IRtmService> rtmInstance_;
std::shared_ptr<ar::rtm::IChannel> channelHandler_;

void Init() {
  RtmEventCallback_.reset(new RtmEventHandler());
  ar::rtm::IRtmService* p_rs = ar::rtm::createRtmService();
  rtmInstance_.reset(p_rs, [](ar::rtm::IRtmService* p) {
  p->release();
  });

  if (!rtmInstance_) {
    cout << "rtm service created failure!" << endl;
    exit(0);
  }

  if (rtmInstance_->initialize(APP_ID.c_str(), RtmEventCallback_.get())) {
    cout << "rtm service initialize failure! appid invalid?" << endl;
    exit(0);
  }
}

登录

APP 必须在登录 RTM 服务器之后，才可以使用 RTM 的点对点消息和群聊功能。在此之前，请确保 rtmInstance_ 初始化完成。

  • 传入能标识用户角色和权限的 Token。如果安全要求不高，也可以将值设为 APPID。Token 需要在应用程序的服务器端生成。
  • 传入能标识每个用户的 ID。用户 ID 为字符串，必须是可见字符（可以带空格），不能为空或者多于 64 个字符，也不能是字符串 "null"。
  • 传入结果回调，用于接收登录 RTM 服务器成功或者失败的结果回调
bool login(const std::string& token, const std::string& uid) {
  if (rtmInstance_->login(token.c_str(), uid.c_str())) {
    cout << "login failed!" << endl;
    return false;
  }
  return true;
}

如果需要退出登录，可以调用 logout() 方法，退出登录之后可以调用 login() 重新登录或者切换账号。

void logout() {
  rtmInstance_->logout();
}

点对点消息

在成功登录 RTM 服务器之后，可以开始使用 RTM 的点对点消息功能。

发送点对点消息

调用 sendMessageToPeer 方法发送点对点消息。在该方法中：

  • 传入目标消息接收方的用户 ID。
  • 传入 RtmMessage 对象实例。该消息对象由 rtmInstance_ 类的的 createMessage() 实例方法创建，并使用消息实例的 setText() 方法设置消息内容。
  • 传入消息发送结果监听器，用于接收消息发送结果回调，如：服务器已接收，发送超时，对方不可达等。
void sendMessageToPeer(std::string peerID, std::string msg) {
  anyRTC::rtm::IMessage* rtmMessage = rtmInstance_->createMessage();
  rtmMessage->setText(msg.c_str());
  int ret = rtmInstance_->sendMessageToPeer(peerID.c_str(),
                                  rtmMessage);
  rtmMessage->release();
  if (ret) {
    cout << "send message to peer failed! return code: " << ret
         << endl;
  }
}

接收点对点消息

点对点消息的接收通过创建 rtmInstance_ 实例的时候传入的 RtmEventCallback_ 实例进行监听。在该实例的 void onMessageReceivedFromPeer(const char *peerId, const anyRTC::rtm::IMessage *message) 回调方法中：

  • 通过 message->getText() 方法可以获取到消息文本内容。
  • peerId 是消息发送方的用户 ID。

频道消息

App 在成功登录 RTM 服务器 之后，可以开始使用 RTM 的频道消息功能。

创建加入频道实例

  • 传入能标识每个频道的 ID。ID 为字符串，必须是可见字符（可以带空格），不能为空或者多于 64 个字符，也不能是字符串 "null"。
  • 指定实例 channelEventCallback_ SDK 通过回调通知应用程序频道的状态变化和运行事件等，如: 接收到频道消息、用户加入和退出频道等。
void joinChannel(const std::string& channel) {
  string msg;
  channelEventCallback_.reset(new ChannelEventHandler(channel));
  channelHandler_.reset(rtmInstance_->createChannel(channel.c_str(), channelEventCallback_.get()))
  if (!channelHandler_) {
    cout << "create channel failed!" << endl;
  }
  channelHandler_->join();
}

发送频道消息

在成功加入频道之后，用户可以开始向该频道发送消息。

调用频道实例的 sendMessage() 方法向该频道发送消息。在该方法中：

  • 传入 RtmMessage 对象实例。该消息对象由 rtmInstance_ 类的 createMessage() 实例方法创建，并使用消息实例的 setText() 方法设置消息内容。
  • 传入消息发送结果监听器，用于接收消息发送结果回调，如：服务器已接收，发送超时等。
void sendGroupMessage (const std::string& msg) {
  anyRTC::rtm::IMessage* rtmMessage = rtmInstance_->createMessage();
  rtmMessage->setText(msg.c_str());
  channelHandler_->sendMessage(rtmMessage);
  rtmMessage->release();
}

接收频道消息

频道消息的接收通过回调实例函数onMessageReceived(const char* userId,const anyRTC::rtm::IMessage *msg)。

退出频道

调用实例的 leave() 方法可以退出该频道。退出频道之后可以调用 join() 方法再重新加入频道。

开发注意事项

  • RTM 支持多个相互独立的 IRtmService 实例。

  • 在收发点对点消息或进行其他频道操作前，请确保你已成功登录 anyRTC RTM 系统（即确保已经收到 onLoginSuccess）。

  • 使用频道核心功能前必须通过调用 createChannel 方法创建频道实例。

  • 你可以创建多个 IRtmService) 客户端实例，但是每个客户端实例最多只能同时加入 20 个频道。每个频道都应有不同的 channelId 参数。

  • 当离开了频道且不再加入该频道时，可以调用 release) 方法及时释放频道实例所占用的资源。

  • 接收到的 IMessage 消息对象不能重复利用再用于发送。