多房间

---

1 功能简介

同一个用户可以同时加入多个房间，并同时在多个房间内推流、拉流、发送实时消息和接收消息回调。

1.1 应用场景

本功能可以隔离多个房间的消息及回调，实现更灵活的连麦业务。ZEGO 推荐用于跨房间连麦和在线教育的超级小班场景。

• 跨房间连麦

主播 A 与主播 B 进行跨房间连麦，主播 A 可以通知房间 A 中所有观众登录主播 B 的房间进行拉流，主播 B 同样可以通知房间 B 中所有观众登录主播 A 的房间进行拉流。

• 超级小班

老师进入大班房间推流，学生都登录大班房间拉流，同时登录小组房间与同组学生讨论和连麦。助教老师登录小组房间维持课堂秩序或解答学生问题。

2 前提条件

在实现多房间功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理。
• 已在项目中集成 ZEGO LiveRoom SDK（2021年6月18日以后），实现基本的实时音视频功能，详情请参考 快速开始 - 集成 等。
• 已联系 ZEGO 技术支持开通多房间功能。

3 使用步骤

以同一用户加入两个房间为例，整体实现流程如下：

1. 在初始化 SDK 之前，将房间模式设置为多房间。
2. 初始化 SDK，根据实际需要，配置房间相关信息。
3. 加入第一个房间，成功登录后，可在该房间内推流、拉流、发送和接收实时消息。
4. 加入第二个房间，成功登录后，可在该房间内推流、拉流、发送和接收实时消息。
5. 离开第一个和第二个房间，针对离开房间不做时序上的限制。

具体功能的实现如下：

3.1 设置多房间模式

必须在初始化 SDK 之前，将房间模式 ZegoRoomMode 设置为多房间模式 “ZegoRoomModeMultiRoom”。

// 设置房间模式为多房间模式
SetRoomMode(ZegoRoomMode::ZegoRoomModeMultiRoom);

3.2 登录房间

3.2.1 设置房间配置信息

• 设置房间配置信息

调用 SetRoomConfig 接口设置允许观众创建房间以及用户状态更新回调，在房间创建之前设置有效，多房间模式下必须带上房间 ID。

bool audienceCreateRoom = true;
bool userStateUpdate = false;
SetRoomConfig(audienceCreateRoom, userStateUpdate, "roomid");

• 设置房间最大在线人数

调用 SetRoomMaxUserCount 接口设置房间最大在线人数，在房间创建之前设置有效，多房间模式下必须传入房间 ID。

SetRoomMaxUserCount(100, "roomid");

• 设置 Token

调用 SetToken 接口设置房间的鉴权 Token，Token 的生成规则请参考 用户权限控制。

在 Token 快要过期的前 30s，会收到 OnTokenWillExpired 回调通知。重新生成 Token 后再调用 SetToken 接口设置。

std::string token = "create token"; 
SetToken(token.c_str(), "roomid");

3.2.2 注册房间回调接口

在登录房间前，注册房间相关的接口。

// 当前对象实现 IRoomCallback 类
SetRoomCallback(this);

房间相关的所有回调接口都会带上房间 ID 参数，用于区分是哪个房间的回调。相关回调如下：

• OnLoginRoom：登录房间通知。

// 参数 pszRoomID 表示房间 ID
void OnLoginRoom(int errorCode, const char *pszRoomID, const ZegoStreamInfo *pStreamInfo, unsigned int streamCount);

• OnKickOut ：用户被踢出房间通知，会停止该用户在房间的推拉流。

// 参数 pszRoomID 表示房间 ID
void OnKickOut(int reason, const char *pszRoomID, const char* pszCustomReason="");

• OnDisconnect ：客户端与 server 断开通知，会停止该房间的推拉流。

// 参数 pszRoomID 表示房间 ID
void OnDisconnect(int errorCode, const char *pszRoomID);

• OnTempBroken ：客户端与 server 的连接被动断开通知，不会停止该房间的推拉流。

// 参数 pszRoomID 表示房间 ID
void OnTempBroken(int errorCode, const char *pszRoomID);

• OnReconnect ：客户端与 server 重连成功通知，不会停止该房间的推拉流。

// 参数 pszRoomID 表示房间 ID
void OnReconnect(int errorCode, const char *pszRoomID);

3.2.3 登录房间

传入房间 ID 等参数，调用 LoginRoom 接口登录房间。

• 单房间模式下，同一时间只能登录一个房间，调用 LoginRoom 接口时，如果之前已经登录其他房间，SDK 内部会自动退出之前的房间，然后登录新房间。
• 多房间模式下，同一时间可以登录多个房间，当超过最大房间个数后，会返回错误码“52005022”。

LoginRoom("roomid", 1, "room_title");

3.3 推流

传入房间 ID 等参数，调用 StartPublishingWithParams 接口在指定房间内推流。

ZegoPublishStreamParams params;
params.streamID = "streamid";
params.streamTitle = "title";
params.publishFlag = ZegoPublishFlag::ZEGO_JOIN_PUBLISH;
params.publishParams = "";
params.channelIndex = PublishChannelIndex::PUBLISH_CHN_MAIN;
params.roomID = "roomid";

StartPublishingWithParams(params);

3.4 拉流

传入房间 ID 等参数，调用 StartPlayingStreamWithParams 接口在指定房间内拉流。

ZegoPlayStreamParams params;
params.streamID = "streamid";
params.displayView = view; // display view
params.extraInfo = nullptr; // extra info
params.roomID = "roomid";

StartPlayingStreamWithParams(params);

3.5 发送、接收实时消息

• 广播消息

调用 SendRoomMessageEx 接口发送广播消息，房间其他用户通过 OnRecvRoomMessage 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送
SendRoomMessageEx(ZegoMessageType::Text, ZegoMessageCategory::Chat, "message", "roomid");

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
void OnRecvRoomMessage(ROOM::ZegoRoomMessage *pMessageInfo, unsigned int messageCount, const char *pszRoomID);

• 弹幕消息

弹幕消息，主要用于大并发的场景，发送一些非必须到达的消息。

调用 SendBigRoomMessage 接口发送弹幕消息，房间其他用户通过 OnRecvBigRoomMessage 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送
SendBigRoomMessage(ZegoMessageType::Text, ZegoMessageCategory::Chat, "message", "roomid");

// 房间其他人收到消息，通过房间 ID 来区分是哪个房间发送的
void OnRecvBigRoomMessage(ROOM::ZegoBigRoomMessage *pMessageInfo, unsigned int messageCount, const char *pszRoomID);

• 自定义信令

自定义信令，指定房间里的用户（可以指定多个），发送特定的消息。

调用 SendCustomCommand 接口发送自定义信令，房间其他用户通过 OnRecvCustomCommand 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送
std::vector<ROOM::ZegoUser> users;
...
SendCustomCommand(users.data(), user.size(), "message", "roomid");

// 接收
void OnRecvCustomCommand(const char *pszUserId, const char *pszUserName, const char *pszContent, const char *pszRoomID);

• 房间附加信息

调用 SetRoomExtraInfo 接口发送房间附加信息，房间其他用户通过 OnRoomExtraInfoUpdated 回调接收消息，可通过房间 ID 来区分是哪个房间发送的。

// 发送，一个房间内只允许 1 个 key 
SetRoomExtraInfo("key", "value", "roomid");

// 接收，通过 SetRoomExtraInfoCallback(IRoomExtraInfoCallback* pCB) 注册回调
void OnRoomExtraInfoUpdated(const char *pszRoomID, const ROOM::ZegoRoomExtraInfo *pExtraInfoList, unsigned int extraInfoListCount);

3.6 退出房间

传入房间 ID ，调用 LogoutRoom 接口退出房间。

• 单房间模式下，退出房间，同时会停止所有的推拉流。
• 多房间模式下，退出房间必须传入房间 ID，只会退出指定房间，并停止该房间的推拉流。

LogoutRoom("roomid");

4 API 参考列表

5 常见问题

1. 调用 SetRoomMode 接口返回失败，是什么原因？

• 是否在初始化 SDK 之前调用 SetRoomMode 接口。
• 是否特殊编包，带有 LoginMultiRoom 接口是无法开启多房间模式的。
• 是否特殊编包，无房间模式是无法开启多房间模式的。
• 是否传入正确的参数。

2. 调用 LoginRoom，回调 OnLoginRoom 登录失败，错误码为 “62001016”。是什么原因？

在没有开通多房间功能的情况下设置了多房间模式，登录房间会失败，返回错误码 62001016。

3. 调用 LoginRoom，回调 OnLoginRoom 登录失败，错误码为 “52005022”。是什么原因？

同时登录的房间数超过最大房间个数后会返回错误码 52005022。目前默认最多同时加入 5 个房间，如有更多需求，请联系 ZEGO 技术支持提供扩展能力。