房间资料管理
功能简介
ZIM SDK 提供了房间信息查询功能，比如获取房间成员列表、查询在线人数等。
实现流程
说明
用户只有在所查询的房间内，才可以使用以下房间功能。
查询房间成员列表
如果用户加入房间后，想要了解此房间的成员构成，可以调用 queryRoomMemberList 接口，传入参数 roomID，config，然后通过 ZIMRoomMemberQueriedCallback 中的 onRoomMemberQueried 回调接口，返回房间内成员列表。
如果用户加入房间后，想要了解此房间的成员构成，可以调用 QueryRoomMemberList 接口，传入参数 roomID，config，然后通过 ZIMRoomMemberQueriedCallback 回调接口，返回房间内成员列表。
如果用户加入房间后，想要了解此房间的成员构成，可以调用 queryRoomMemberList 接口，传入参数 roomID，config，然后通过 ZIMRoomMemberQueriedResult 回调接口，返回房间内成员列表。
如果用户加入房间后，想要了解此房间的成员构成，可以调用 queryRoomMemberList 接口，传入参数 roomID，config，即可获取到房间内成员列表。
其中，参数 config 表示查询房间成员操作的配置，需要通过 ZIMRoomMemberQueryConfig 类的以下参数进行配置：
| 参数 | 参数类型 | 是否必填 | 描述 |
|---|---|---|---|
| nextFlag | string | 是 | 分页查询的标识位。首次查询时，请将此字段设为空字符串。 若回调的 "nextFlag" 字段不是空字符串，说明还未查询完所有用户，此时需要将其设置为当前位置，以继续下一页的查询。 |
| count | int | 是 | 查询一次，可获取的成员数量。 注意事项：分页获取消息以降低开销，建议单次获取 100 个成员以内。 |
说明
当房间成员超过 500 人时，查询房间成员列表的结果最多只能包含 500 名成员的信息。如需提高查询结果上限，请联系 ZEGO 技术支持进行配置。
ZIMRoomMemberQueryConfig zimQueryMemberConfig = new ZIMRoomMemberQueryConfig();
zimQueryMemberConfig.count = 100;
zim.queryRoomMemberList(roomID, zimQueryMemberConfig, new ZIMRoomMemberQueriedCallback() {
@Override
public void onRoomMemberQueried(String roomID, ArrayList<ZIMUserInfo> memberList, String nextFlag, ZIMError errorInfo) {
}
});ZIMRoomMemberQueryConfig zimQueryMemberConfig = new ZIMRoomMemberQueryConfig();
zimQueryMemberConfig.count = 100;
zim.queryRoomMemberList(roomID, zimQueryMemberConfig, new ZIMRoomMemberQueriedCallback() {
@Override
public void onRoomMemberQueried(String roomID, ArrayList<ZIMUserInfo> memberList, String nextFlag, ZIMError errorInfo) {
}
});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) {
//当操作失败时，将触发此操作。
});ZIMRoomMemberQueryConfig *config = [[ZIMRoomMemberQueryConfig alloc] init];
config.nextFlag = @"";
config.count = 1;//1 表示每次获取一个成员。
[zim queryRoomMemberListByRoomID:RoomID config:config callback:^(NSArray<ZIMUserInfo * > * _Nonnull memberList, NSString * _Nonnull nextFlag, ZIMError * _Nonnull errorInfo) {
//在这里实现获取房间成员列表的事件回调。
}];ZIMRoomMemberQueryConfig *config = [[ZIMRoomMemberQueryConfig alloc] init];
config.nextFlag = @"";
config.count = 1;//1 表示每次获取一个成员。
[zim queryRoomMemberListByRoomID:RoomID config:config callback:^(NSArray<ZIMUserInfo * > * _Nonnull memberList, NSString * _Nonnull nextFlag, ZIMError * _Nonnull errorInfo) {
//在这里实现获取房间成员列表的事件回调。
}];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);
}
});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);
}
});ZIMRoomMemberQueryConfig zimQueryMemberConfig = new ZIMRoomMemberQueryConfig();
zimQueryMemberConfig.count = 100;
ZIM.GetInstance().QueryRoomMemberList("roomID", zimQueryMemberConfig, (string roomID, List<ZIMUserInfo> memberList, string nextFlag, ZIMError errorInfo) =>
{
}
);ZIMRoomMemberQueryConfig zimQueryMemberConfig = new ZIMRoomMemberQueryConfig();
zimQueryMemberConfig.count = 100;
ZIM.GetInstance().QueryRoomMemberList("roomID", zimQueryMemberConfig, (string roomID, List<ZIMUserInfo> memberList, string nextFlag, ZIMError errorInfo) =>
{
}
);const roomID = '';
const config: ZIMRoomMemberQueryConfig = { count: 10, nextFlag: '' };
zim.queryRoomMemberList(roomID, config)
.then((res: ZIMRoomMemberQueriedResult) => {
// 查询成功。
})
.catch((err: ZIMError) => {
// 查询失败。
});const roomID = '';
const config: ZIMRoomMemberQueryConfig = { count: 10, nextFlag: '' };
zim.queryRoomMemberList(roomID, config)
.then((res: ZIMRoomMemberQueriedResult) => {
// 查询成功。
})
.catch((err: ZIMError) => {
// 查询失败。
});批量查询房间用户信息
开发者可以通过调用 queryRoomMembers 接口，传入 roomID 、 userID 数组，批量查询房间中用户的信息。接口调用成功后， ZIMRoomMembersQueriedCallback 会返回查询成功的 userList（可用于确认目标用户在房间中），以及查询失败的 errorUserList（可用于确认目标用户不在房间中）。
说明
批量查询用户数量的默认上限为 10 名。
示例代码如下所示：
String targetUserID = "targetUserIdA";
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add(targetUserID);
// userID 映射 ZIMRoomMemberInfo 的 map，可以缓存起来用于后续 UI 展示，目前 ZIMRoomMemberInfo 暴露了 userID , userName。
HashMap<String,ZIMRoomMemberInfo> roomMemberMap = new HashMap<>();
ZIM.getInstance().queryRoomMembers(userIDs, "targetRoomID", new ZIMRoomMembersQueriedCallback() {
@Override
public void onRoomMembersQueried(String roomID, ArrayList<ZIMRoomMemberInfo> memberList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if(errorInfo.code != ZIMErrorCode.SUCCESS){
Log.d("ZIM CallBack","query room members error! error code:"+errorInfo.code+", error message:"+errorInfo.message);
}
HashMap<String,ZIMErrorUserInfo> targetErrorUserInfoMap = new HashMap<>();
for (ZIMRoomMemberInfo memberInfo:
memberList) {
roomMemberMap.put(memberInfo.userID,memberInfo);
}
// 针对查询失败的部分 userID, 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
for (ZIMErrorUserInfo errorUserInfo:
errorUserList) {
targetErrorUserInfoMap.put(errorUserInfo.userID,errorUserInfo);
}
// 判断是否目标成员是否在房间内
boolean isTargetUserIdA = roomMemberMap.containsKey(targetUserID);
}
});String targetUserID = "targetUserIdA";
ArrayList<String> userIDs = new ArrayList<>();
userIDs.add(targetUserID);
// userID 映射 ZIMRoomMemberInfo 的 map，可以缓存起来用于后续 UI 展示，目前 ZIMRoomMemberInfo 暴露了 userID , userName。
HashMap<String,ZIMRoomMemberInfo> roomMemberMap = new HashMap<>();
ZIM.getInstance().queryRoomMembers(userIDs, "targetRoomID", new ZIMRoomMembersQueriedCallback() {
@Override
public void onRoomMembersQueried(String roomID, ArrayList<ZIMRoomMemberInfo> memberList, ArrayList<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo) {
if(errorInfo.code != ZIMErrorCode.SUCCESS){
Log.d("ZIM CallBack","query room members error! error code:"+errorInfo.code+", error message:"+errorInfo.message);
}
HashMap<String,ZIMErrorUserInfo> targetErrorUserInfoMap = new HashMap<>();
for (ZIMRoomMemberInfo memberInfo:
memberList) {
roomMemberMap.put(memberInfo.userID,memberInfo);
}
// 针对查询失败的部分 userID, 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
for (ZIMErrorUserInfo errorUserInfo:
errorUserList) {
targetErrorUserInfoMap.put(errorUserInfo.userID,errorUserInfo);
}
// 判断是否目标成员是否在房间内
boolean isTargetUserIdA = roomMemberMap.containsKey(targetUserID);
}
});NSString *userIdA = @"targetUserIdA";
NSString *userIdB = @"targetUserIdB";
NSArray<NSString *> *targetUserIDs = @[userIdA,userIdB];
// userID 映射 ZIMRoomMemberInfo 的 map, 可以缓存起来用于后续 UI 展示，目前 ZIMRoomMemberInfo 暴露了 userID , userName。
NSMutableDictionary *targetRoomMemberMap = [[NSMutableDictionary alloc] init];
[[ZIM getInstance] queryRoomMembersByUserIDs:targetUserIDs roomID:@"targetRoomID" callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberInfo *> * _Nonnull memberList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
if(errorInfo.code != ZIMErrorCodeSuccess){
NSLog(@"query room members failed! error code:%ld, error message: %@",errorInfo.code, errorInfo.message);
return;
}
// userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
NSMutableDictionary *targetErrorUserInfoMap = [[NSMutableDictionary alloc] init];
for (ZIMRoomMemberInfo *currentMemberInfo in memberList) {
[targetRoomMemberMap setObject:currentMemberInfo forKey:currentMemberInfo.userID];
}
for (ZIMErrorUserInfo *currentErrorUserInfo in errorUserList){
[targetErrorUserInfoMap setObject:currentErrorUserInfo forKey:currentErrorUserInfo.userID];
}
// 判断是否目标成员是否在房间内
bool isTargetUserIdAInTheRoom = [[targetRoomMemberMap allKeys] containsObject:userIdA];
}];NSString *userIdA = @"targetUserIdA";
NSString *userIdB = @"targetUserIdB";
NSArray<NSString *> *targetUserIDs = @[userIdA,userIdB];
// userID 映射 ZIMRoomMemberInfo 的 map, 可以缓存起来用于后续 UI 展示，目前 ZIMRoomMemberInfo 暴露了 userID , userName。
NSMutableDictionary *targetRoomMemberMap = [[NSMutableDictionary alloc] init];
[[ZIM getInstance] queryRoomMembersByUserIDs:targetUserIDs roomID:@"targetRoomID" callback:^(NSString * _Nonnull roomID, NSArray<ZIMRoomMemberInfo *> * _Nonnull memberList, NSArray<ZIMErrorUserInfo *> * _Nonnull errorUserList, ZIMError * _Nonnull errorInfo) {
if(errorInfo.code != ZIMErrorCodeSuccess){
NSLog(@"query room members failed! error code:%ld, error message: %@",errorInfo.code, errorInfo.message);
return;
}
// userID 映射 ZIMErrorUserInfo 的 map, 如果有需要关注失败原因可以读取此数据结构
NSMutableDictionary *targetErrorUserInfoMap = [[NSMutableDictionary alloc] init];
for (ZIMRoomMemberInfo *currentMemberInfo in memberList) {
[targetRoomMemberMap setObject:currentMemberInfo forKey:currentMemberInfo.userID];
}
for (ZIMErrorUserInfo *currentErrorUserInfo in errorUserList){
[targetErrorUserInfoMap setObject:currentErrorUserInfo forKey:currentErrorUserInfo.userID];
}
// 判断是否目标成员是否在房间内
bool isTargetUserIdAInTheRoom = [[targetRoomMemberMap allKeys] containsObject:userIdA];
}];string userIdA = "UserIdA";
string userIdB = "UserIdB";
List<string> userIDs = new List<string>();
userIDs.Add(userIdA);
userIDs.Add(userIdB);
ZIM.GetInstance().QueryRoomMembers(userIDs, "roomID", (string roomID, List<ZIMRoomMemberInfo> memberList, List<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo)=>{
if (errorInfo.code == ZIMErrorCode.Success){
//调用成功
}
});string userIdA = "UserIdA";
string userIdB = "UserIdB";
List<string> userIDs = new List<string>();
userIDs.Add(userIdA);
userIDs.Add(userIdB);
ZIM.GetInstance().QueryRoomMembers(userIDs, "roomID", (string roomID, List<ZIMRoomMemberInfo> memberList, List<ZIMErrorUserInfo> errorUserList, ZIMError errorInfo)=>{
if (errorInfo.code == ZIMErrorCode.Success){
//调用成功
}
});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){
// 处理失败
});
const userIDs = ['user1', 'user2'];
zim.queryRoomMembers(userIDs, 'roomID')
.then((res: ZIMRoomMembersQueriedResult) => {
// 这里写查询结果返回后的业务逻辑
});
const userIDs = ['user1', 'user2'];
zim.queryRoomMembers(userIDs, 'roomID')
.then((res: ZIMRoomMembersQueriedResult) => {
// 这里写查询结果返回后的业务逻辑
});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();
});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(roomID, new ZIMRoomOnlineMemberCountQueriedCallback() {
@Override
public void onRoomOnlineMemberCountQueried(String roomID, int count, ZIMError errorInfo) {
}
});// 查询房间在线人数
zim.queryRoomOnlineMemberCount(roomID, new ZIMRoomOnlineMemberCountQueriedCallback() {
@Override
public void onRoomOnlineMemberCountQueried(String roomID, int count, ZIMError errorInfo) {
}
});// 获取在线房间成员数量
ZIM
.getInstance()
.queryRoomOnlineMemberCount('roomID')
.then((value) {
// 当操作成功时触发此处代码
})
.catchError((onError) {
// 当操作失败时触发此处代码
});// 获取在线房间成员数量
ZIM
.getInstance()
.queryRoomOnlineMemberCount('roomID')
.then((value) {
// 当操作成功时触发此处代码
})
.catchError((onError) {
// 当操作失败时触发此处代码
});[zim queryRoomOnlineMemberCountByRoomID:< #(nonnull NSString *) #> callback:^(NSString * _Nonnull roomID, unsigned int count, ZIMError * _Nonnull errorInfo) {
//实现查询在线房间成员的事件回调。
}];[zim queryRoomOnlineMemberCountByRoomID:< #(nonnull NSString *) #> callback:^(NSString * _Nonnull roomID, unsigned int count, ZIMError * _Nonnull errorInfo) {
//实现查询在线房间成员的事件回调。
}];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);
}
});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);
}
});// 获取在线房间成员数量
ZIM.GetInstance().QueryRoomOnlineMemberCount("房间ID", (string roomID, uint count, ZIMError errorInfo) =>
{
}
);// 获取在线房间成员数量
ZIM.GetInstance().QueryRoomOnlineMemberCount("房间ID", (string roomID, uint count, ZIMError errorInfo) =>
{
}
);const roomID = '';
zim.queryRoomOnlineMemberCount(roomID)
.then((res: ZIMRoomOnlineMemberCountQueriedResult) => {
// 查询成功。
})
.catch((err: ZIMError) => {
// 查询失败。
});const roomID = '';
zim.queryRoomOnlineMemberCount(roomID)
.then((res: ZIMRoomOnlineMemberCountQueriedResult) => {
// 查询成功。
})
.catch((err: ZIMError) => {
// 查询失败。
});说明
加入到房间后，如果调用了 logout 接口退出登录，该客户端即处于离线状态。
获取房间用户扩展字段信息
用户加入房间后，通过 ZIMUserInfo.userExtendedData 字段可获取到该用户进房前的扩展信息快照。此功能可以用于实现房间用户等级、VIP 用户标识等业务场景。
注意
此接口无法获取用户加入房间后修改的扩展字段信息（例如：进房前的 userExtendedData 为 extended1，进房后修改为 extended2，通过该接口获取的内容还是 extended1）。
相关接口请参考：queryRoomMemberList、queryRoomMembers、onRoomMemberJoined、onRoomMemberLeft。
说明
- 2.22.0 版本开始支持。
- 如需开启此功能请联系 ZEGO 技术支持。