ZIM SDK 提供多人房间聊天功能,支持用户向房间内发送文本消息或自定义消息,实现了多人在线交流、同步分享。
多人房间聊天功能可应用于小班课或者会议室等场景,房间成员数量上限请参考 计费说明。
在实现“房间管理”功能之前,请确保:
用户可以通过以下两种方式,创建房间并进入房间。
房间内的用户,可以通过 sendRoomMessage 接口,向房间内发送消息,详情请参考 收发房间消息。
如果 roomID 已存在:
如果 roomID 不存在:
以下流程中,我们以客户端 A 创建并加入房间,客户端 B 加入房间为例。
所有进入房间的用户,都需注册 onRoomMemberJoined、onRoomMemberLeft 和 onRoomStateChanged 回调,用于监听房间其他成员的变动和接收房间连接状态发生改变的事件通知。
注册 onRoomMemberJoined 回调示例源码:
void onRoomMemberJoined(ZIM * /*zim*/, const std::vector<ZIMUserInfo> & /*memberList*/,
const std::string & /*roomID*/) override{
}
注册 onRoomMemberLeft 回调示例源码:
void onRoomMemberLeft(ZIM * /*zim*/, const std::vector<ZIMUserInfo> & /*memberList*/,
const std::string & /*roomID*/) override{
}
注册 onRoomStateChanged 回调示例源码:
void onRoomStateChanged(ZIM * /*zim*/, ZIMRoomState /*state*/, ZIMRoomEvent /*event*/,
const std::string & /*extendedData*/,
const std::string & /*roomID*/)override{
}
客户端 A 登录后,创建一个房间,可以调用 createRoom 接口,传入 ZIMRoomInfo 信息,即可创建并加入房间。同时可以通过错误信息 error_info
中的错误码 ZIMErrorCode
类型的参数值,判断是否创建成功。相关错误码请查看 常见错误码。
创建成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 ZIM_ROOM_STATE_CONNECTED, ZIMRoomEvent 为 ZIM_ROOM_EVENT_SUCCESS。
// roomID 最大 32 字节的字符串。仅支持数字,英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// roomName 最大 64 字节的字符串,无特殊字符限制。
ZIMRoomInfo room_info;
room_info.roomID = room_id;
room_info.roomName = room_name;
zim_->createRoom(room_info, [=](ZIMRoomFullInfo room_info, zim::ZIMError error_info) {
global_main_dialog_->PostUiThread([=] {});
if (error_info.code != 0)
{
ShowMsg(L"创建房间失败,房间ID: %s, 错误码: %d", room_info.baseInfo.roomID, error_info.code);
}
else
{
ShowMsg(L"创建房间成功,房间ID: %s", room_info.baseInfo.roomID);
}
});
客户端 B 加入房间,可以调用 joinRoom 接口,传入由 A 创建的房间 roomID,即可加入房间。同时可以根据错误码 ZIMErrorCode
的参数值,判断用户是否加入成功。相关错误码请查看 常见错误码。
加入成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 ZIM_ROOM_STATE_CONNECTED, ZIMRoomEvent 为 ZIM_ROOM_EVENT_SUCCESS。
zim_->joinRoom(roomId, [=](ZIMRoomFullInfo room_info, zim::ZIMError error_info) {
global_main_dialog_->PostUiThread([=] {});
if (error_info.code != 0)
{
ShowMsg(L"加入房间失败,房间ID: %s, 错误码: %d", room_info.baseInfo.roomID, error_info.code);
}
else
{
ShowMsg(L"加入房间成功,房间ID: %s, 房间名称: %s", room_info.baseInfo.roomID, room_info.baseInfo.roomName);
}
});
当房间有其他成员加入时,将通过 setEventHandler 的回调接口 onRoomMemberJoined,向其他已在成员发送消息通知。
例如,当客户端 B 加入由 A 创建的房间时,A 将收到房间内成员变动的通知。
void onRoomMemberJoined(ZIM* zim, const std::vector<ZIMUserInfo>& member_list, const std::string& room_id)
{
for (auto member : member_list)
{
ShowMsg(L"用户: (%s%s), 进入房间: %s", member.userID, member.userName, room_id);
}
}
以下流程中,我们以客户端 X 创建并进入房间,客户端 Y 直接进入房间为例。
ZIMRoomInfo room_info;
room_info.roomID = room_id;
room_info.roomName = room_name;
ZIMRoomAdvancedConfig config;
zim_->enterRoom(room_info, config, [=](ZIMRoomFullInfo room_info, zim::ZIMError error_info) {
global_main_dialog_->PostUiThread([=] {});
if (error_info.code != 0)
{
ShowMsg(L"进入房间失败,房间ID: %s, 错误码: %d", room_info.baseInfo.roomID, error_info.code);
}
else
{
ShowMsg(L"进入房间成功,房间ID: %s", room_info.baseInfo.roomID);
}
});
If a user wants to switch from one room to another, the user can call the switchRoom method, passing in the ID of the original room (fromRoomID
) and the information of the target room (toRoomInfo
), which includes the room ID and room name. This will allow the user to switch rooms.
However, it is possible for the room switch to fail if the target room does not exist. To avoid this failure, you can also pass isCreateWhenRoomNotExisted
as true
(allowing ZIM to create a new room if the target room does not exist) and config (used to configure the new room) when calling the switchRoom interface. In this case, when ZIM finds that the target room does not exist, it will create a new room based on toRoomInfo
and config
(if provided) for the switch.
After a successful room switch, other users in the original room can be notified of a user leaving the room through the onRoomMemberLeft callback of setEventHandler, and other users in the target room can be notified of a user joining the room through the callback interface onRoomMemberJoined of setEventHandler.
Please refer to the following flowchart for the complete process:
Sample code:
std::string fromRoomID = "fromRoomID";
auto toRoomInfo = zim::ZIMRoomInfo("toRoomID", "toRoomName");
// Whether to create a room if it does not exist.
// Only when this is true and the target room does not exist, the toRoomName and config in toRoomInfo are meaningful
bool isCreateWhenRoomNotExisted = true;
// Advanced configuration for creating a room
auto config = zim::ZIMRoomAdvancedConfig();
config.roomAttributes.emplace("key1", "value1");
config.roomDestroyDelayTime = 90;
// Switch rooms
zim->switchRoom(
fromRoomID, toRoomInfo, isCreateWhenRoomNotExisted, config,
[=](const zim::ZIMRoomFullInfo &roomInfo, const zim::ZIMError &errorInfo) {
if (errorInfo.code == zim::ZIMErrorCode::ZIM_ERROR_CODE_SUCCESS) {
// Room switch successful, you can obtain information about the switched room from roomInfo
}
});
用户如果想要离开房间,可以调用 leaveRoom 接口,传入房间的 roomID,即可退出此房间;房间内的其他用户可以通过 setEventHandler 的回调接口 onRoomMemberLeft,收到成员变动通知。
离开房间成功后会收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 ZIM_ROOM_STATE_DISCONNECTED,ZIMRoomEvent 为 ZIM_ROOM_EVENT_SUCCESS。
离开房间后,将不能收到房间内的消息。
// 离开房间
zim->leaveRoom(room_id, [=](const std::string &roomID, const ZIMError &errorInfo) {
});
// 收到成员变动通知
void onRoomMemberLeft(ZIM* zim, const std::vector<ZIMUserInfo>& member_list, const std::string& room_id)
{
for (auto member : member_list)
{
ShowMsg(L"用户: (%s,%s), 退出房间: %s", member.userID, member.userName, room_id);
}
}
当所有成员离开房间后,房间将自动销毁。ZIM SDK 支持通过 ZIMRoomAdvancedConfig 设置房间延迟销毁,最大延迟为 3 小时。
调用 leaveAllRoom 接口,即可立即离开当前加入的所有房间,并返回离开的房间列表。如果用户多端登录,则用户在一端调用此接口后,仅会退出在该端上加入的房间,在其他端加入的房间不受影响。
zim->leaveAllRoom([](const std::vector<std::string>& roomIDList, const ZIMError& errorInfo) {
if (errorInfo.errorCode == 0) {
//roomIDList 为离开的房间列表
} else {
//根据官网错误码表处理
}
});
房间内的其他用户可以通过 setEventHandler 的回调接口 onRoomMemberLeft,收到成员变动通知。
退出所有房间成功后,用户会根据所离开房间的数量,多次收到 onRoomStateChanged 的通知回调,ZIMRoomState 为 ZIM_ROOM_STATE_DISCONNECTED, ZIMRoomEvent 为 ZIM_ROOM_EVENT_SUCCESS。
离开房间后,将不能收到房间内的消息。
开发者可以在后台调用 ZIM 服务端接口进行 销毁房间。房间被销毁后,用户通过 onRoomStateChanged 收到房间状态(ZIMRoomState)从 ZIM_ROOM_STATE_CONNECTED
转变为 ZIM_ROOM_STATE_DISCONNECTED
的事件通知。根据 ZIM SDK 版本不同,回调中描述导致房间连接状态发生变更的事件(ZIMRoomEvent)如下所示:
ZIM_ROOM_EVENT_KICKED_OUT
。ZIM_ROOM_EVENT_ROOM_NOT_EXIST
。ZIM 房间类似于在线聊天室、网络中断会导致房间进入重连状态并抛出 onRoomStateChanged。详情请参考 场景 4 :ZIM 房间断网。
联系我们
文档反馈