房间资料管理

功能简介

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

实现流程

说明

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

查询房间成员列表

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

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

参数	参数类型	是否必填	描述
nextFlag	string	是	分页查询的标识位。首次查询时，请将此字段设为空字符串。若回调的 "nextFlag" 字段不是空字符串，说明还未查询完所有用户，此时需要将其设置为当前位置，以继续下一页的查询。
count	int	是	查询一次，可获取的成员数量。注意事项：分页获取消息以降低开销，建议单次获取 100 个成员以内。

参数

参数类型

是否必填

描述

nextFlag

string

是

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

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

count

int

是

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

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

说明

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

ZIMRoomMemberQueryConfig roomMemberQueryConfig = ZIMRoomMemberQueryConfig();
roomMemberQueryConfig.count = 100;
ZIM
    .getInstance()
    .queryRoomMemberList('roomID', roomMemberQueryConfig)
    .then((value) {
      //value 是 ZIMRoomMemberQueriedResult 对象。
      //当操作成功时，将触发此操作。
    })
    .catchError((onError) {
      //当操作失败时，将触发此操作。
    });

ZIMRoomMemberQueryConfig roomMemberQueryConfig = ZIMRoomMemberQueryConfig();
roomMemberQueryConfig.count = 100;
ZIM
    .getInstance()
    .queryRoomMemberList('roomID', roomMemberQueryConfig)
    .then((value) {
      //value 是 ZIMRoomMemberQueriedResult 对象。
      //当操作成功时，将触发此操作。
    })
    .catchError((onError) {
      //当操作失败时，将触发此操作。
    });

批量查询房间用户信息

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

说明

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

示例代码如下所示：

ZIM.getInstance().queryRoomMembers(["userA","userB"], "roomID")
.then((ZIMRoomMembersQueriedResult value) {
    // userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
    Map<String, ZIMErrorUserInfo> targetErrorUserInfoMap = {};

    Map<String, ZIMRoomMemberInfo> targetRoomMemberMap = {};

    for (ZIMRoomMemberInfo currentMemberInfo in value.memberList) {
        targetRoomMemberMap[currentMemberInfo.userID] = currentMemberInfo;
    }
    for (ZIMErrorUserInfo currentErrorUserInfo in value.errorUserList) {
       targetErrorUserInfoMap[currentErrorUserInfo.userID] = currentErrorUserInfo;
    }
    // 判断是否目标成员是否在房间内
    bool isTargetUserIdAInTheRoom = targetRoomMemberMap.containsKey(userIdA);
}).catchError((onError){
    // 处理失败
});

ZIM.getInstance().queryRoomMembers(["userA","userB"], "roomID")
.then((ZIMRoomMembersQueriedResult value) {
    // userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
    Map<String, ZIMErrorUserInfo> targetErrorUserInfoMap = {};

    Map<String, ZIMRoomMemberInfo> targetRoomMemberMap = {};

    for (ZIMRoomMemberInfo currentMemberInfo in value.memberList) {
        targetRoomMemberMap[currentMemberInfo.userID] = currentMemberInfo;
    }
    for (ZIMErrorUserInfo currentErrorUserInfo in value.errorUserList) {
       targetErrorUserInfoMap[currentErrorUserInfo.userID] = currentErrorUserInfo;
    }
    // 判断是否目标成员是否在房间内
    bool isTargetUserIdAInTheRoom = targetRoomMemberMap.containsKey(userIdA);
}).catchError((onError){
    // 处理失败
});

查询房间在线人数

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

// 获取在线房间成员数量
ZIM
    .getInstance()
    .queryRoomOnlineMemberCount('roomID')
    .then((value) {
        // 当操作成功时触发此处代码
    })
    .catchError((onError) {
        // 当操作失败时触发此处代码
    });

// 获取在线房间成员数量
ZIM
    .getInstance()
    .queryRoomOnlineMemberCount('roomID')
    .then((value) {
        // 当操作成功时触发此处代码
    })
    .catchError((onError) {
        // 当操作失败时触发此处代码
    });

说明

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

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

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

注意

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

相关接口请参考：queryRoomMemberList、queryRoomMembers、onRoomMemberJoined、onRoomMemberLeft。

说明

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