本文介绍Windows版本AIMSDK的支持系统、集成方法和简单使用示例,通过本文您将了解如何进行SDK集成。

支持系统

支持Window XP及以上,Visual Studio 2017。

集成方法

  1. App导入所需依赖
    说明 DingPaaS基座及其他模块均使用Visual Studio 2017进行编译。
    // DingPaaS 基座SDK
    dps.dll
    // DingPaaS 依赖的基础库
    fml.dll
    // 钉钉定制版 sqlite
    sqlte3.dll
    // openssl 1.1
    libeay32MD.dll
    ssleay32MD.dll
    // IM SDK
    aim.dll
  2. 启动DingPaaS引擎
    #include "dps_engine_c.h"
    #include "dps_version.h"
    #include "aim_c_api.h"
    
    // 创建引擎,仅需创建一次
    DPSPubEngine* engine = CreateDPSPubEngine("DPS_VERSION");
    // engine 实例生命周期由SDK内部管理,不得在App层进行释放
    // 获取engine
    DPSPubEngine* engine2 = GetDPSPubEngine();
    // 释放引擎使用单独API ReleaseDPSPubEngine()
    
    // 获取DingPaaS设置
    auto setting = engine->GetSettingService();
    // 设置必要信息
    setting->setAppKey("appkey");
    setting->setAppID("apitest");
    // 设置本地数据库/数据存储路径, 该路径必须存在,并可有可写权限
    setting->setDataPath("...");
    // 设备唯一ID
    setting->setDeviceId("DeviceID");
    // 构造UA所需的参数
    setting->setAppName("MyDemo"));
    setting->setAppVersion("1.0");
    setting->setDeviceName("...");
    setting->setDeviceType("...");
    setting->setDeviceLocale("...");
    setting->setOSName("...");
    setting->setOSVersion("...");
    setting->setEnvType(DPSEnvType::ENV_TYPE_ONLINE);
    // 向 DingPaaS 服务申请的长链接域名
    setting->setLonglinkServerAddress("...");
    // 向 DingPaaS 服务申请的文件上传服务域名
    setting->setFileUploadServerAddress("...");
    //设置登录token获取回调
    setting->setAuthTokenCallback(std::make_shared<MyDPSPubAuthTokenCallback>());
    
    // 注册 IM 模块, 为单例,App无需手动释放 imInfo
    DPSModuleInfo* imInfo = GetAIMModuleInfo();
    engine->registerModule(imInfo);
    
    // 启动引擎,为异步,成功后,将回调listener::onSuccess()
    engine->start(listener)
    获取token回调
    /**
     * 请求获取Token回调
     */
    class DPSAuthTokenCallback {
     public:
      virtual ~DPSAuthTokenCallback() {}
    
      virtual void OnCallback(
          const DPSUserId& user_id,
          const std::shared_ptr<DPSAuthTokenGotCallback>& on_got,
          DPSAuthTokenExpiredReason reason) = 0;
    };
    
    /**
     * 通知获取到Auth token回调
     */
    class DPSAuthTokenGotCallback {
     public:
      virtual ~DPSAuthTokenGotCallback() {}
    
      /**
       * 通知DPSEngine token获取成功
       */
      virtual void OnSuccess(const DPSAuthToken& auth_token) = 0;
    
      /**
       * 通知DPSEngine token获取失败
       */
      virtual void OnFailure(int32_t error_code, const std::string& error_msg) = 0;
    };
    
    /**
     * Auth token信息
     */
    struct DPSAuthToken final {
      std::string access_token;
      std::string refresh_token;
    
      DPSAuthToken(std::string access_token_, std::string refresh_token_)
          : access_token(std::move(access_token_)),
            refresh_token(std::move(refresh_token_)) {}
    
      DPSAuthToken() {}
    };

使用示例

  • 创建用户实例及登录
    // 创建用户 manager
    DPSPubEngine* engine = GetDPSPubEngine();
    // 创建 1234 用户实例,异步,通过listener监听是否创建完成(内部会进行数据库初始化等操作)
    engine->createDPSManager(“1234”, listener);
    ...
    // 创建manager成功后,获取对应用户的Manger
    auto manager = engine->getDPSManager("1234");
    auto authService = manager->getAuthService();
    authService->addListener(std::make_shared<MyDPSAuthListener>());
    
    // 触发登录
    authService->login();
    
    // 退出登录,当用户主动登出时调用,正常退出应用无需调用,下次启动可免登,内部自动刷新token
    authService->logout();
    DPSAuthListener 登录及连接状态监听
    /**
     * 登录监听
     */
    class DPSAuthListener {
     public:
      virtual ~DPSAuthListener() {}
    
      /**
       * 连接状态事件
       * @param status      网络状态
       */
      virtual void OnConnectionStatusChanged(DPSConnectionStatus status) = 0;
    
      /**
       * 登录token获取失败事件
       * @param error_code  获取登录token失败错误值
       * @param error_msg   获取登录token失败错误信息
       */
      virtual void OnGetAuthCodeFailed(int32_t error_code,
                                       const std::string& error_msg) = 0;
    
      /**
       * 本地登录事件
       * 如果本地已有登录信息,调用Login接口后会立即回调;反之会等待网络登录成功之后回调
       */
      virtual void OnLocalLogin() = 0;
    
      /**
       * 被踢事件
       * @param message     被踢下线时附带的消息
       */
      virtual void OnKickout(const std::string& message) = 0;
    
      /**
       * 其他端设备在(离)线情况
       * @param type 事件类型(1:事件通知,包括上下线,2:状态通知,在线状态)
       * @param device_type 设备类型
       * (0:default,1:web,2:Android,3:iOS,4:Mac,5:Windows,6:iPad)
       * @param status      设备状态(1:上线或在线,2:下线或离线)
       * @param time        时间(上线或下线时间)
       */
      virtual void OnDeviceStatus(int32_t type,
                                  int32_t device_type,
                                  int32_t status,
                                  int64_t time) = 0;
    
      /**
       * 下载资源cookie变更事件
       * @param cookie      新cookie
       */
      virtual void OnMainServerCookieRefresh(const std::string& cookie) = 0;
    };
  • IM相关:获取会话列表
    // 获取用户(1234)对应的 IM module 实例
    // 需要App层持有,manager释放后,手动进行释放
    AIMPubModule* imModule = GetAIMPubModuleInstance("1234");
    // 获取会话服务, convService 为智能指针,可以持有,也可每次获取
    auto convService = imModule->GetConvService();
    // 获取100条会话列表
    convService->ListLocalConversationsWithOffset(0, 100,
        [](const std::vector<AIMPubConversation> &result){
            // 注:SDK 的回调均在单独的callback 线程,不能进行UI操作,也不能进行耗时的操作
            // ...
        },
        [](const ::alibaba::dps::DPSError &error){
            // ...
        });
  • IM相关:创建会话
    // 获取用户(1234)对应的 IM module 实例
    // 需要App层持有,manager释放后,手动进行释放
    AIMPubModule* imModule = GetAIMPubModuleInstance("1234");
    // 获取会话服务, convService 为智能指针,可以持有,也可每次获取
    auto convService = imModule->GetConvService();
    
    // 单聊会话
    AIMPubConvCreateSingleConvParam param;;
    param.uids = {"1234", "5678"}; // 单聊双方UID
    convService->CreateSingleConversation(param, [](const AIMPubConversation &conv){
            // 创建会话成功
        },
        [](const ::alibaba::dps::DPSError &error){
            // 创建会话失败
        });
    
    // 创建群聊会话
    auto groupService = imModule->GetGroupService();
    AIMPubGroupCreateGroupConvParam param;
    AIMPubGroupUserInfo user1;
    user1.uid = "1234";
    user1.nick_name = "昵称1";
    AIMPubGroupUserInfo user2;
    user2.uid = "4567";
    user2.nick_name = "昵称2";
    param.user_infos = {user1, user2};
    param.title = "title";
    groupService->CreateGroupConversation(param, 
        [](const AIMPubConversation &conv){
            // 创建成功
        },
        [](const ::alibaba::dps::DPSError &error){
            // 创建失败
        });
  • IM相关:发送消息
    // 获取用户(1234)对应的 IM module 实例
    // 需要App层持有,manager释放后,手动进行释放
    AIMPubModule* imModule = GetAIMPubModuleInstance("1234");
    // 获取消息服务, msgService 为智能指针,可以持有,也可每次获取
    auto msgService = imModule->GetMsgService();
    
    // 构造文本消息内容
    AIMMsgTextContent textContent;
    textContent.text = "Hello ";
    
    // 构造消息内容
    AIMMsgContent msgContent;
    msgContent.contentType = AIMMsgContentType::CONTENT_TYPE_TEXT;
    msgContent.textContent = textContent;
    
    // 构造消息
    AIMPubMsgSendMessage sendMessage;
    sendMessage.content = msgContent;
    sendMessage.receivers = conv.userids;
    sendMessage.cid = conv.cid;
    
    msgService->sendMessage(sendMessage,
        [](double progress){
            // 图片等多媒体消息的发送进度
        },
        [](const AIMPubMessage &msg){
            // 消息发送成功
        },
        [](const ::alibaba::dps::DPSError &error){
            // 消息发送失败
        });
  • IM相关:接收消息
    // 获取用户(1234)对应的 IM module 实例
    // 需要App层持有,manager释放后,手动进行释放
    AIMPubModule* imModule = GetAIMPubModuleInstance("1234");
    // 获取消息服务, msgService 为智能指针,可以持有,也可每次获取
    auto msgService = imModule->GetMsgService();
    msgService->AddMsgListener(listener);
    
    // listener 继承该虚接口
    /**
     * 消息变更监听
     */
    class AIMPubMsgListener {
    public:
      virtual ~AIMPubMsgListener() {}
    
      /**
       * 消息新增
       * 发送消息或收到推送消息时,触发该回调
       * 当从服务端拉取历史消息时,不会触发该回调
       * @param msgs 新增消息
       */
      virtual void OnAddedMessages(const std::vector<AIMPubNewMessage> &msgs) = 0;
    
      /**
       * 消息删除
       * @param msgs 变更消息
       */
      virtual void OnRemovedMessages(const std::vector<AIMPubMessage> &msgs) = 0;
    
      /**
       * 当消息数据库内有消息添加时,触发该回调
       * 包括发送,推送及拉取历史消息
       * 注意:
       * 1. 不保证传入消息 msgs 的顺序
       * 2. onStored 回调的顺序也不保证消息组间的顺序
       * @param msgs 变更消息
       */
      virtual void OnStoredMessages(const std::vector<AIMPubMessage> &msgs) = 0;
    };