实现聊天室消息收发

更新时间： 2024/08/22 17:21:31

聊天室是网易云信 IM 即时通讯服务中一种比群组更加开放、更加自由的组织形态，可帮助您实现真正意义上的大型聊天室，参与人数无上限，又可满足消息到达的实时性要求，主要应用于娱乐直播、教育直播等场景。

本文介绍如何通过较少的代码集成 NetEase IM SDK （以下简称 NIM SDK）并调用相关 API，在您的应用中实现聊天室消息收发。

使用前准备

已在云信控制台创建应用，获取 App Key。
已注册云信 IM 账号，获取云信 IM 账号和 token。
已开通和配置聊天室功能。
已调用服务端接口创建聊天室。
NIM SDK 兼容的系统包括 Windows 7、Windows 8/8.1、Windows 10、macOS 10.10（仅支持 x86_64 架构，不支持 i386）。

实现流程

流程概览

实现聊天室消息收发的流程，可分为下图所示的 4 大步骤。

步骤 1：集成 SDK

为降低接入成本，NetEase IM SDK （以下简称 NIM SDK）C++ 封装层使用 CMake 进行管理，根据不同的情况您在接入 C++ 封装层时可能需要适当的修改，新的发布目录拆分为如下结构：

├─bin
├─include
├─lib
└─wrapper

bin/lib 目录存放 NIM SDK 的动态库文件, 在您发布时请打包使用到的模块，lib后缀为 Windows 下的动态库符号链接文件
- (lib)nim(.dll|.so|.dylib):即时通讯, 含圈组
- (lib)nim_chatroom(.dll|.so|.dylib): 聊天室
- (lib)h_available(.dll|.so|.dylib): 高可用模块, 被以上两个模块所依赖
- (lib)nim_tools_http(.dll|.so|.dylib): http 工具库，若不使用wrapper/nim_tools_cpp_wrapper/nim_tools_http_cpp.h中的接口可去除
- nim_audio.dll: 音频解码库，仅支持 Windows 环境，若不使用wrapper/nim_tools_cpp_wrapper/nim_audio_cpp.h中的接口可去除
- nrtc.dll: 音视频通话库，仅支持 Windows 环境，若不使用wrapper/nim_cpp_wrapper/api/nim_cpp_vchat.h中的接口可去除
- node-nim.node: NIM SDK Node 封装层, 用于 Electron 以及 Node.js 环境下的接入，其他情况可去除
- 其他如msvcp120.dll、msvcr120.dll等（系统）依赖
include 目录存放了 NIM C SDK 的导出头文件
wrapper 目录存放了 C++ 封装层的源代码

如果您仅使用 V10 接口，只需将 include 目录添加到头文件搜索路径，代码中包含对应头文件即可使用，无需进行以下步骤。

这里主要介绍以 CMake 工程接入的方式，更多接入方式（包括 VS、Qt、Xcode等传统方式）请参见[集成 SDK](https://doc.yunxin.163.com/messaging2/guide/zQ3MzQyMzQ?platform=client)。

使用 add_subdirectory 命令将 wrapper 目录添加为子目录。
使用 include_directories 方法将 include 和 wrapper 文件夹添加为头文件搜索路径。
根据您的执行目标使用 target_link_libraries 按需添加链接库即可。链接库如下：
- nim_cpp_wrapper NIM C++ 封装层库
- nim_chatroom_cpp_wrapper Chatroom C++ 封装层库
- nim_wrapper_util NIM 及 Chatroom C++ 封装层库通用的工具库
- nim_tools_cpp_wrapper NIM HTTP 组件 C++ 封装层库
- nim_qchat_cpp_wrapper NIM QChat 圈组 C++ 封装层库

不建议将 CMake 产生的工程文件直接引用到项目中使用，因为 CMake 使用将绝对路径写入到工程的配置文件（.vcxproj）中，您在自己设备上生成的工程文件无法在其他设备中顺利编译。
如果您的工程项目已经是基于 CMake 管理，则只需将 wrapper 工程作为您主项目的依赖即可，其他无需任何多余配置。如果您的工程项目不是基于 CMake 管理的，那么建议您在持续集成（Continuous Integration, CI）或者与其他同事协作时，通过自定义脚本在项目编译前始终执行 CMake 来生成并编译工程得到需要的二进制文件产物。

示例代码如下：

# CMakeLists.txt
cmake_minimum_required(VERSION 3.10)
project(nim_demo)
 
include_directories(${CMAKE_CURRENT_LIST_DIR}/include
                    ${CMAKE_CURRENT_LIST_DIR}/wrapper)
add_subdirectory(wrapper)
add_executable(${PROJECT_NAME} main.cpp)
target_link_libraries(${PROJECT_NAME}
                      nim_cpp_wrapper
                      nim_chatroom_cpp_wrapper
                      nim_wrapper_util
                      nim_tools_cpp_wrapper
                      nim_qchat_cpp_wrapper)

步骤 2：初始化 SDK

将 SDK 集成到客户端后，需要先完成 SDK 的初始化才能使用其他功能。

引入 SDK 动态库文件。

将 V10 NIM SDK 提供了不同平台的动态库文件，不同平台下的区别如下：
- Windows 下后缀为 .dll，您需要将动态库文件放置到应用程序相同目录。
- macOS 下后缀为 .dylib，您需要在打包应用时将 .dylib 文件放置到 YouApp.app/Contents/Frameworks 目录下。
- Linux 下后缀为 .so，与 Windows 一样与应用程序放置到同一个目录下即可。
Windows SDK 基于 MSVC15（2017）开发，如果 App 没有对应的运行时库文件，请在安装应用时部署微软提供的 MSVC 2017 运行时库组件。

调用 init 方法初始化 SDK，推荐在应用程序启动时初始化。初始化成功后，即可使用 V10 所有的 API。

int main(int argc, char* argv[]) {
	v2::V2NIMInitOption option;
	auto error = v2::V2NIMClient::get().init(option);
	if (error) {
		// handle error
		return -1;
	}
	error = v2::V2NIMClient::get().uninit();
	if (error) {
		// handle error
		return -1;
	}
	return 0;
}

更多初始化相关说明，请参见初始化 SDK。

步骤 3: 登录聊天室

调用 newInstance 方法创建聊天室实例。调用成功后，返回聊天室实例（instanceId），聊天室实例与聊天室（roomId）形成一一绑定关系。

cppauto chatroomClient = V2NIMChatroomClient::newInstance();
if (!chatroomClient) {
    // create instance failed
    // ...
    return;
}
auto instanceId = chatroomClient->getInstanceId();
// save instanceId to cache
// ...

调用 addChatroomClientListener 方法注册聊天室登录相关监听器，包括聊天室连接状态变更、进出聊天室、被踢出聊天室。

cppV2NIMChatroomClientListener listener;
listener.onChatroomStatus = [](V2NIMChatroomStatus status, nstd::optional<V2NIMError> error) {
    // handle chatroom status
};
listener.onChatroomEntered = []() {
    // handle chatroom entered
};
listener.onChatroomExited = [](nstd::optional<V2NIMError> error) {
// handle chatroom exited
};
listener.onChatroomKicked = [](V2NIMChatroomKickedInfo kickedInfo) {
    // handle chatroom kicked
};
chatroomClient.addChatroomClientListener(listener);

在登录聊天室之前，需要先提前获取聊天室地址。可以通过以下两种方式获取：
- 若当前客户端已登录 IM，那么可以通过 getChatroomLinkAddress 方法获取指定聊天室的地址。
```
cpploginService.getChatroomLinkAddress(
    "roomId",
    [](nstd::vector<nstd::string> linkAddresses) {
        // handle link addresses
    },
    [](V2NIMError error) {
        // handle error
    });
```
- 若当前客户端未登录 IM，那么 SDK 无法获取聊天室服务器的地址，需要客户端向开发者应用服务器请求该地址，而应用服务器需要向网易云信服务器请求，然后将请求结果原路返回给客户端。具体请参考获取聊天室地址服务端 API。

调用 enter 方法登录聊天室。

cppV2NIMChatroomEnterParams enterParams;
enterParams.accountId = "accountId";
enterParams.token = "token";
enterParams.roomNick = "nick";
enterParams.roomAvatar = "avatar";
enterParams.linkProvider = [](nstd::string roomId, nstd::string account) {
    nstd::vector<nstd::string> linkAddresses;
    // get link addresses
    // ...
    return linkAddresses;
};
enterParams.serverExtension = "server extension";
enterParams.notificationExtension = "notification extension";
chatroomClient.enter(
    "roomId",
    enterParams,
    [](V2NIMChatroomEnterResult result) {
        // enter succeeded
    },
    [](V2NIMError error) {
        // enter failed, handle error
    });

登录聊天室成功后，调用 getChatroomService方法获取聊天室服务。后续聊天室相关操作（聊天室成员、消息等）均在返回的 V2NIMChatroomService 类中实现。
```
cppauto& chatroomService = client.getChatroomService();
```

步骤4: 聊天室消息收发

NIM SDK 支持多种消息类型，包括文本消息、图片消息、语音消息、视频消息、文件消息、地理位置消息、提示消息、通知消息以及自定义消息。

本节以发送方与接收方的消息交互为例，介绍通过 NIM SDK 快速实现聊天室文本消息收发的流程。其他类型消息收发相关详情，请参见聊天室消息管理。

接收方注册聊天室监听器，监听聊天室消息接收回调事件 onReceiveMessages。

示例代码如下：

cppV2NIMChatroomListener listener;
listener.onReceiveMessages = [](nstd::vector<V2NIMChatroomMessage> messages) {
    // handle receive messages
};
chatroomService.addChatroomListener(listener);

发送方调用 createTextMessage 方法，构建一条文本消息。并调用 sendMessage 方法，发送已构建的文本消息。

示例代码如下：

cpp// 创建一条文本消息
auto message = V2NIMChatroomMessageCreator::createTextMessage("hello world");
auto params = V2NIMSendChatroomMessageParams();
// 发送消息
chatroomService.sendMessage(
    message,
    params,
    [](V2NIMSendChatroomMessageResult result) {
        // send message succeeded
    },
    [](V2NIMError error) {
        // send message failed, handle error
    },
    [](uint32_t progress) {
        // upload progress
    });

接收方通过 onReceiveMessages 回调收到聊天室消息。

后续步骤

为保障通信安全，如果您在调试环境中的使用的是云信控制台生成的测试用 IM 账号和 Token，请确保在后续的正式生产环境中，将其替换为通过新版 IM 服务端 API生成的正式 IM 账号和 token。

使用前准备

实现流程

流程概览

步骤 1：集成 SDK

步骤 2：初始化 SDK

步骤 3: 登录聊天室

步骤4: 聊天室消息收发

后续步骤

相关参考