logo
当前页

房间资料管理


功能简介

ZIM SDK 提供了房间信息查询功能,比如获取房间成员列表、查询在线人数等。

实现流程

说明

用户只有在所查询的房间内,才可以使用以下房间功能。

查询房间成员列表

如果用户加入房间后,想要了解此房间的成员构成,可以调用 queryRoomMemberList 接口,传入参数 roomID,config,即可获取到房间内成员列表。

其中,参数 config 表示查询房间成员操作的配置,需要通过 ZIMRoomMemberQueryConfig 类的以下参数进行配置:

参数参数类型是否必填描述
nextFlagstring

分页查询的标识位。首次查询时,请将此字段设为空字符串。

若回调的 "nextFlag" 字段不是空字符串,说明还未查询完所有用户,此时需要将其设置为当前位置,以继续下一页的查询。

countint

查询一次,可获取的成员数量。

注意事项:分页获取消息以降低开销,建议单次获取 100 个成员以内。

说明

当房间成员超过 500 人时,查询房间成员列表的结果最多只能包含 500 名成员的信息。如需提高查询结果上限,请联系 ZEGO 技术支持进行配置。

ZIMRoomMemberQueryConfig config;
config.count = count;
config.nextFlag = string_flag;

zim_->queryRoomMemberList(string_room_id, config, [=](const std::vector<ZIMUserInfo>& member_list, const std::string& next_flag, zim::ZIMError error_info) {
    if (error_info.code != 0)
    {
        ShowMsg(L"获取房间成员列表失败,房间ID:%s", string_room_id);
    }
    else
    {
        CString string_user_list;
        for (auto& member : member_list)
        {
            CString string_user;
            string_user.Format(L"(%s,%s),", member.userID, member.userName);
            string_user_list += string_user;
        }

        ShowMsg(L"获取房间成员列表成功,房间ID:%s,数量:%d,用户:%s,下一页标志:%s", string_room_id, member_list.size(), string_user_list, next_flag);
    }
});

批量查询房间用户信息

开发者可以通过调用 queryRoomMembers 接口,传入 roomID 、 userID 数组,批量查询房间中用户的信息。接口调用成功后, ZIMRoomMembersQueriedCallback 会返回查询成功的 userList(可用于确认目标用户在房间中),以及查询失败的 errorUserList(可用于确认目标用户不在房间中)。

说明

批量查询用户数量的默认上限为 10 名。

示例代码如下所示:

std::vector<std::string> targetUserIDs;

ZIM::getInstance().queryRoomMembers(targetUserIDs, roomID, [targetRoomMemberMap](const std::string &roomID, const std::vector<ZIMRoomMemberInfo> &memberList,const std::vector<ZIMErrorUserInfo> &errorUserList, const ZIMError &errorInfo) {
    if (errorInfo.code != ZIMErrorCodeSuccess) {
        std::cout << "Query room members failed! error code: " << errorInfo.code << ", error message: " << errorInfo.message << std::endl;
        return;
    }

// userID 映射 ZIMRoomMemberInfo 的 map, 可以缓存起来用于后续 UI 展示,目前 ZIMRoomMemberInfo 暴露了 userID , userName。
    std::map<std::string, ZIMRoomMemberInfo> targetRoomMemberMap;

 // userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
    std::map<std::string, ZIMErrorUserInfo> targetErrorUserInfoMap;

    for (auto const& currentMemberInfo : memberList) {
        targetRoomMemberMap[currentMemberInfo.userID] = currentMemberInfo;
    }
    for (auto const& currentErrorUserInfo : errorUserList) {
        targetErrorUserInfoMap[currentErrorUserInfo.userID] = currentErrorUserInfo;
    }

// 判断是否目标成员是否在房间内
    bool isTargetUserIdAInTheRoom = std::find(targetRoomMemberMap.begin(), targetRoomMemberMap.end(), userIdA) != targetRoomMemberMap.end();
});

查询房间在线人数

用户还可以获取到房间内的在线人数,调用 queryRoomOnlineMemberCount 接口,输入 roomID,即可查询到房间内的在线人数。

zim_->queryRoomOnlineMemberCount(string_room_id, [=](unsigned int count, zim::ZIMError error_info) {
    if (error_info.code != 0)
    {
        ShowMsg(L"查询在线房间成员数量失败,房间ID:%s", string_room_id);
    }
    else
    {
        ShowMsg(L"查询在线房间成员数量成功,房间ID:%s", string_room_id);
    }
});
说明

加入到房间后,如果调用了 logout 接口退出登录,该客户端即处于离线状态。

获取房间用户扩展字段信息

用户加入房间后,通过 ZIMUserInfo.userExtendedData 字段可获取到该用户进房前的扩展信息快照。此功能可以用于实现房间用户等级、VIP 用户标识等业务场景。

注意

此接口无法获取用户加入房间后修改的扩展字段信息(例如:进房前的 userExtendedData extended1,进房后修改为 extended2,通过该接口获取的内容还是 extended1)。

相关接口请参考:queryRoomMemberListqueryRoomMembersonRoomMemberJoinedonRoomMemberLeft

说明
  • 2.22.0 版本开始支持。
  • 如需开启此功能请联系 ZEGO 技术支持。

Previous

房间管理

Next

房间属性管理

当前页

返回到顶部