JMessage PC SDK 开发指南

概述

JMessage PC SDK , 使用 C++语言开发, 基于 Web SDK 协议，提供易用的 C++ 接口

编译器支持 VS2017(msvc141)，兼容系统 Windows 7、Windows 8/8.1、Windows 10

MacOS 支持 Xcode 10, MacOS 10.13 (x86_64)

功能

实时消息，离线消息，单聊，群聊，聊天室等
消息类型支持文本，语音，图片，文件，位置，自定义消息等
基于cpprestsdk的 task/then 异步接口(更多关于 task) ，上层可以使用回调或 co_await 协程方式调用异步接口
功能基于 WEB SDK，开发者可参考 Web SDK

鉴权

SDK 在初始化的时候，需要提供相关参数

appkey : 开发者在极光平台注册的 IM 应用 appkey
randomStr : 20-36 长度的随机字符串，作为签名 salt 使用
timestamp : 当前时间戳，用于防止重放攻击，精确到毫秒
signature : 签名，10 分钟后失效

签名生成算法如下:

signature = md5("appkey={appkey}&timestamp={timestamp}&random_str={randomStr}&key={secret}")

          signature = md5("appkey={appkey}&timestamp={timestamp}&random_str={randomStr}&key={secret}")

此代码块在浮窗中显示

其中 secret 为开发者在极光平台注册的 IM 应用 masterSecret

不建议在客户端计算签名，有泄漏 masterSecret 的风险

//签名生成示例(Qt): auto timestamp = QDateTime::currentDateTime().toMSecsSinceEpoch(); auto str = QString("appkey=007a1134fb361233c566a1cc&timestamp=%1&random_str=022cd9fd995849b58b3ef0e943421ed9&key=122d61038232226fc12d0422").arg(time); auto signature = QCryptographicHash::hash(str.toUtf8()， QCryptographicHash::Md5).toHex().toStdString();

          //签名生成示例(Qt):
auto timestamp = QDateTime::currentDateTime().toMSecsSinceEpoch();
auto str = QString("appkey=007a1134fb361233c566a1cc&timestamp=%1&random_str=022cd9fd995849b58b3ef0e943421ed9&key=122d61038232226fc12d0422").arg(time);

auto signature = QCryptographicHash::hash(str.toUtf8()， QCryptographicHash::Md5).toHex().toStdString();

此代码块在浮窗中显示

快速开始

依赖

Windows

编译器:VS2017(msvc141)
第三方库: https://github.com/Microsoft/cpprestsdk

MacOS

编译器:Xcode 10 Toolchain
第三方库:cpprestsdk, 安装命令 brew install cpprestsdk

简单示例

1.使用 SDK 包

Windows:使用 NuGet 程序包，在 Visual Studio 中右键单击你的项目，选择管理Nuget程序包

选择浏览页，搜索jmessage-cpp ，然后安装需要的版本 SDK 即可
手动下载相应平台的 SDK

Windows SDK 包括:
- include: 头文件
- lib: 链接库
- bin:动态库
Mac SDK 包括:
- Jmcpp.framework

2.创建 Client

Client 类提供了 SDK 的主要功能，所以先创建一个 Client 对象
Configuration 参数配置 Client，包括 SDK 缓存路径，日志级别等，一般默认即可

#include <Jmcpp/Client.h> // 包含头文件 Jmcpp::Configuration cfg; // 默认配置 Jmcpp::Client client(cfg); //创建Client对象

           #include <Jmcpp/Client.h> // 包含头文件
 Jmcpp::Configuration cfg; // 默认配置
 Jmcpp::Client client(cfg); //创建Client对象

此代码块在浮窗中显示

3.在登录前， SDK 应该设置相应的监听回调，处理消息接收与事件

SDK 提供监听消息接收的回调接口，消息分为实时消息(用户在线时收到的消息)与离线消息

// 监听消息 client.onMessageReceive([](Jmcpp::MessagePtr msg) { auto content = msg->content; if(std::holds_alternative<Jmcpp::TextContent>(content)) { auto&& imageCont = std::get<Jmcpp::TextContent>(content); std::cout << msg->sender.username << " send to " << msg->receiver.username << " : " << imageCont.text << std::endl; } else if(std::holds_alternative<Jmcpp::ImageContent>(content)) { } else { } }); // 监听同步消息 client.onMessageSync([](std::vector<Jmcpp::MessagePtr> msgs) { });

              // 监听消息
    client.onMessageReceive([](Jmcpp::MessagePtr msg)
    {
        auto content = msg->content;
        if(std::holds_alternative<Jmcpp::TextContent>(content))
        {
            auto&& imageCont = std::get<Jmcpp::TextContent>(content);
            std::cout
                << msg->sender.username << " send to "
                << msg->receiver.username << " : "
                << imageCont.text
                << std::endl;
        }
        else if(std::holds_alternative<Jmcpp::ImageContent>(content))
        {

        }
        else
        {
        }
    });

    // 监听同步消息
    client.onMessageSync([](std::vector<Jmcpp::MessagePtr> msgs)
    {
    });

此代码块在浮窗中显示

SDK 提供监听事件的回调接口，同样事件分为实时事件与同步事件

// 监听实时事件 client.onEventReceive([](Jmcpp::Event ev) { if(std::holds_alternative<Jmcpp::ForceLogoutEvent>(ev)) { auto&& e = std::get<Jmcpp::ForceLogoutEvent>(ev); } else if(std::holds_alternative<Jmcpp::MessageRetractedEvent>(ev)) { auto&& e = std::get<Jmcpp::MessageRetractedEvent>(ev); } else { //... } }); // 监听事件同步 client.onEventSync([](std::vector<Jmcpp::Event> ev) { //... });

              // 监听实时事件
    client.onEventReceive([](Jmcpp::Event ev)
    {
        if(std::holds_alternative<Jmcpp::ForceLogoutEvent>(ev))
        {
            auto&& e = std::get<Jmcpp::ForceLogoutEvent>(ev);

        }
        else if(std::holds_alternative<Jmcpp::MessageRetractedEvent>(ev))
        {
            auto&& e = std::get<Jmcpp::MessageRetractedEvent>(ev);

        }
        else
        {
            //...
        }
    });

    // 监听事件同步
    client.onEventSync([](std::vector<Jmcpp::Event> ev)
    {
        //...
    });

此代码块在浮窗中显示

4.登录，鉴权，发送消息

SDK 登录注册需要开发者鉴权，其中签名开发者应该通过某个服务或其它方式得到，不建议在客户端通过 masterSecret 计算，这里只是演示用法

Jmcpp::Authorization auth; auth.appKey = "25b693b31d2c2ad5f072ef0c"; auth.randomStr = "022cd9fd995849b58b3ef0e943421ed9"; auth.timestamp = "1467967210887";// 使用时应该获取当前事件戳，这里只是演示 auth.signature = "D97C2DDA3E46E5E6D482E9E8EE84AF93";//使用时应该动态计算得到，这里只是演示 //登录 client.login("yourUsername", "yourPassword",auth).get(); // 创建一条文本消息内容 auto content = client.createTextContent("hello!").get(); // 创建消息，包含要发送的用户或群 auto msg = client.buildMessage(Jmcpp::UserId("targetUsername"), content); // 发送消息 client.sendMessage(msg).get();

           Jmcpp::Authorization auth;
 auth.appKey = "25b693b31d2c2ad5f072ef0c";
 auth.randomStr = "022cd9fd995849b58b3ef0e943421ed9";
 auth.timestamp = "1467967210887";// 使用时应该获取当前事件戳，这里只是演示
 auth.signature = "D97C2DDA3E46E5E6D482E9E8EE84AF93";//使用时应该动态计算得到，这里只是演示

 //登录
 client.login("yourUsername", "yourPassword",auth).get();

 // 创建一条文本消息内容
 auto content = client.createTextContent("hello!").get();
 // 创建消息，包含要发送的用户或群
 auto msg = client.buildMessage(Jmcpp::UserId("targetUsername"), content);
 // 发送消息
 client.sendMessage(msg).get();

此代码块在浮窗中显示

5.退出登录，销毁 Client

client.logout();

            client.logout();

此代码块在浮窗中显示

6.错误处理

try{ client.login("yourUsername", "yourPassword", getAuthorization()).get(); auto content = client.createTextContent("hello!").get(); auto msg = client.buildMessage(Jmcpp::UserId("test"), content); client.sendMessage(msg).get(); client.logout(); } catch(Jmcpp::ServerException& e) { // API 服务器调用返回的错误 std::cout << e.what() << std::endl; } catch(std::system_error& e) { // API 调用产生的其它错误 std::cout << e.what() << std::endl; }

          try{
        client.login("yourUsername", "yourPassword", getAuthorization()).get();
        auto content = client.createTextContent("hello!").get();
        auto msg = client.buildMessage(Jmcpp::UserId("test"), content);
        client.sendMessage(msg).get();
        client.logout();
    }
    catch(Jmcpp::ServerException& e)
    {
        // API 服务器调用返回的错误
        std::cout << e.what() << std::endl;
    }
    catch(std::system_error& e)
    {
        // API 调用产生的其它错误
        std::cout << e.what() << std::endl;
    }

此代码块在浮窗中显示

完整 SDK 使用可以参考Windows JChat

参考文档

错误码定义：IM web SDK 错误码列表

完整 API 文档：JMessage PC SDK API