概述(Windows)

最近更新时间:2019-08-02 16:39:46

本文主要介绍腾讯云 IM SDK 的几个最基本功能的使用方法,阅读此文档有助于您对即时通信 IM 的基本使用流程有一个简单的认识。

初始化

在使用 SDK 进行即时通信 IM 操作之前,需要初始 SDK。
示例:

int sdk_app_id = 12345678;
std::string json_init_cfg;
Json::Value json_value_dev;
json_value_dev[kTIMDeviceInfoDevId] = "12345678";
json_value_dev[kTIMDeviceInfoPlatform] = TIMPlatform::kTIMPlatform_Windows;
json_value_dev[kTIMDeviceInfoDevType] = "";

Json::Value json_value_init;
json_value_init[kTIMSdkConfigLogFilePath] = path;
json_value_init[kTIMSdkConfigConfigFilePath] = path;
json_value_init[kTIMSdkConfigAccountType] = "107";
json_value_init[kTIMSdkConfigDeviceInfo] = json_value_dev;

TIMInit(sdk_app_id, json_value_init.toStyledString().c_str());

SDKAppID 可以在即时通信 IM 控制台 创建应用后获取到。更多初始化操作请参考 初始化 文档。

登录/登出

登录

  • 用户登录腾讯后台服务器后才能正常收发消息,登录需要用户提供 identifier、userSig。详细请参阅 登录鉴权 文档。
  • 登录为异步过程,通过回调函数返回是否成功,成功后方能进行后续操作。登录成功或者失败会主动调用提供的回调。

示例:

const void* user_data = nullptr; // 回调函数回传
const char* id = "WIN01"; 
const char* user_sig = "WIN01UserSig";
TIMLogin(id, user_sig, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (code != ERR_SUCC) {
        // 登入失败
        return;
    }
    //登入成功

}, user_data);
注意:

code 表示错误码,desc 表示错误描述,具体可参阅 错误码 文档。

onForceOffline

如果此用户在其他终端被踢,登录将会失败,返回错误码(ERR_IMSDK_KICKED_BY_OTHERS:6208),如果用户被踢了,请务必用 Alert 等提示窗提示用户,关于被踢的详细描述,参阅 用户状态变更

onUserSigExpired
每一个 userSig 都有一个过期时间,如果 userSig 过期,login 将会返回 70001 错误码,如果您收到这个错误码,可以向您的业务服务器重新请求新的 userSig,参阅 用户票据过期

登出

如用户主动注销或需要进行用户的切换,则需要调用注销操作。

示例:

const void* user_data = nullptr; // 回调函数回传
TIMLogout([](int32_t code, const char* desc, const char* json_param, const void* user_data) { 
    if (code != ERR_SUCC) { 
        // 登出失败
        return;
    }
    // 登出成功

}, user_data);
注意:

在需要切换帐号时,需要 Logout 回调成功或者失败后才能再次 Login,否则 Login 可能会失败。
更多登录/登出操作请参考 登录登出 文档。

消息发送

会话获取

会话是指面向一个人或者一个群组的对话,通过与单个人或群组之间会话收发消息,发消息时首先需要先获取会话,获取会话需要指定会话类型(群组或者单聊),以及会话对方标志(对方帐号或者群号)。

获取对方 identifier 为 Windows-02 的单聊会话示例:

const void* user_data = nullptr; // 回调函数回传
const char* userid = "Windows-02";
int ret = TIMConvCreate(userid, kTIMConv_C2C, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    // 回调返回会话的具体信息
}, user_data);
if (ret != TIM_SUCC) {
    // 调用 TIMConvCreate 接口失败
}

获取群组 ID 为 Windows-Group-01 的群聊会话示例:

const void* user_data = nullptr; // 回调函数回传
const char* groupid = "Windows-Group-01";
int ret = TIMConvCreate(groupid, kTIMConv_Group, [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    // 回调返回会话的具体信息
}, user_data);
if (ret != TIM_SUCC) {
    // 调用 TIMConvCreate 接口失败
}

消息发送

IM SDK 中的消息由 TIMMessage 表示, 每个 TIMMessage 由多个 TIMElem 组成,每个 TIMElem 单元可以是文本,也可以是图片,也就是说每一条消息可包含多个文本、多张图片、以及其他类型的单元。

示例:

const void* user_data = nullptr; // 回调函数回传
Json::Value json_value_text;
json_value_text[kTIMElemType] = kTIMElem_Text;
json_value_text[kTIMTextElemContent] = "Message Send to Windows-02";
Json::Value json_value_msg;
json_value_msg[kTIMMsgElemArray].append(json_value_text);

const char* userid = "Windows-02";
int ret = TIMMsgSendNewMsg(userid, kTIMConv_C2C, json_value_msg.toStyledString().c_str(), [](int32_t code, const char* desc, const char* json_param, const void* user_data) {
    if (code != ERR_SUCC) { 
        // 发送消息成功失败
        return;
    }
    // 发送消息成功成功

}, user_data);
if (ret != TIM_SUCC) {
    // 调用 TIMMsgSendNewMsg 接口失败
}

消息接收

在多数情况下,用户需要感知新消息的通知,这时只需注册新消息监听回调 TIMSetRecvNewMsgCallback,在用户登录状态下,会拉取离线消息,为了不漏掉消息通知,需要在登录之前注册新消息监听回调。

设置消息监听示例:

// 设置新消息监听器,收到新消息时,通过此监听器回调
const void *user_data = nullptr;
TIMSetRecvNewMsgCallback([](const char* json_msg_array, const void* user_data) {
    Json::Value json_value_msgs; // 解析消息
    Json::Reader reader;
    if (!reader.parse(json_msg_array, json_value_msgs)) {
        printf("reader parse failure!%s", reader.getFormattedErrorMessages().c_str());
        return;
    }
    for (Json::ArrayIndex i = 0; i < json_value_msgs.size(); i++) {  // 遍历Message
        Json::Value& json_value_msg = json_value_msgs[i];
        Json::Value& elems = json_value_msg[kTIMMsgElemArray];
        for (Json::ArrayIndex m = 0; m < elems.size(); m++) {   // 遍历Elem
            Json::Value& elem = elems[i];

            uint32_t elem_type = elem[kTIMElemType].asUInt();
            if (elem_type == TIMElemType::kTIMElem_Text) {  // 文本

            }else if (elem_type == TIMElemType::kTIMElem_Sound) {  // 声音

            } else if (elem_type == TIMElemType::kTIMElem_File) {  // 文件

            } else if (elem_type == TIMElemType::kTIMElem_Image) { // 图片

            }
        }
    }

}, user_data);

更多消息收发操作请参考 消息发送消息接收

群组管理

即时通信 IM 有多种群组类型,其特点以及限制因素可参考 群组系统,群组使用唯一 ID 标识,通过群组 ID 可以进行不同操作,其中群组相关操作都由 TIMGroupManager 实现,需要用户登录成功后操作。

类型 说明
私有群(Private) 适用于较为私密的聊天场景,群组资料不公开,只能通过邀请的方式加入,类似于微信群。
公开群(Public) 适用于公开群组,具有较为严格的管理机制、准入机制,类似于 QQ 群。
聊天室(ChatRoom) 群成员可以随意进出。
直播聊天室(AVChatRoom) 与聊天室相似,但群成员人数无上限;支持以游客身份(不登录)接收消息。
在线成员广播大群(BChatRoom) 适用于需要向全体在线用户推送消息的场景。

创建群组

以下示例创建一个叫 Windows-Group-01 公开群组,并且把用户 Windows_002 拉入群组。
示例:

Json::Value json_group_member_array(Json::arrayValue);
// 初始群成员
Json::Value json_group_member;
json_group_member[kTIMGroupMemberInfoIdentifier] = "Windows_002";
json_group_member[kTIMGroupMemberInfoMemberRole] = kTIMGroupMemberRoleFlag_Member;
json_group_member_array.append(json_group_member);

Json::Value json_value_createparam;
json_value_createparam[kTIMCreateGroupParamGroupId] = "Windows-Group-01";
json_value_createparam[kTIMCreateGroupParamGroupType] = kTIMGroup_Public;
json_value_createparam[kTIMCreateGroupParamGroupName] = "Windows-Group-Name";
json_value_createparam[kTIMCreateGroupParamGroupMemberArray] = json_group_member_array;

json_value_createparam[kTIMCreateGroupParamNotification] = "group notification";
json_value_createparam[kTIMCreateGroupParamIntroduction] = "group introduction";
json_value_createparam[kTIMCreateGroupParamFaceUrl] = "group face url";
json_value_createparam[kTIMCreateGroupParamMaxMemberCount] = 2000;
json_value_createparam[kTIMCreateGroupParamAddOption] = kTIMGroupAddOpt_Any;

const void* user_data = nullptr;
int ret = TIMGroupCreate(json_param.c_str(), [](int32_t code, const char* desc, const char* json_params, const void* user_data) {
    if (code != ERR_SUCC) { 
        // 创建群组失败
        return;
    }

    // 创建群组成功 解析Json获取创建后的GroupID

}, user_data))

更多群组操作请参考 SDK 文档 群组管理

群组消息

群组消息与 C2C (单聊)消息相同,仅在发送时填写群组的 ID 和类型kTIMConv_Group,可参阅 SDK 文档 消息发送 部分。