房间属性管理
功能简介
ZIM SDK 的房间属性功能,提供了可在指定房间中,设置自定义属性的能力。
通常可以应用在语音直播、聊天室等的属性同步、语聊房的麦位管理、以及狼人杀等卡牌类游戏中,记录用户的角色和牌局状态等场景中。
实现流程
开发者需要在调用 createRoom 接口时,设置房间属性参数,创建并加入房间。
注意
- 每个房间中,最多允许设置 20 个属性,以
Key-Value
的方式进行存储。Key
的长度上限为 16 字节,Value
的长度上限为 1024 字节,所有属性的总长度不得超过 5120 字节。开发者如果需要提高属性上限,请联系 ZEGO 技术支持。 - 房间销毁后,设置的自定义属性也会同时销毁。
示例代码
zim::ZIMRoomInfo room_info;
room_info.roomID = "房间ID";
room_info.roomName = "房间名称";
zim::ZIMRoomAdvancedConfig advanced_info;
advanced_info.roomAttributes.emplace("key", "value");
zim_->createRoom(
room_info, advanced_info, [=](zim::ZIMRoomFullInfo roomInfo,
zim::ZIMError errorInfo) {
});
1
设置房间属性
每个房间中,设置的属性以 Key-Value
的形式存储。
- 当 Key 不存在时,设置房间属性表示增加属性。
- 当 key 已经存在时,设置房间属性表示更新已有属性的取值。
示例代码
std::unordered_map<std::string, std::string> roomAttributes;
roomAttributes.emplace("key", "value");
zim->setRoomAttributes(roomAttributes, room_id, nullptr, [=](const std::string &roomID, const std::vector<std::string> &errorKeyList,const ZIMError &errorInfo){});
1
删除房间属性
通常开发者只能删除自己拥有的属性,也可以设置 “config” 中的 “isForce” 参数取值,删除他人创建的属性。
示例代码
std::vector<std::string> keys;
keys.push_back("key");
zim->deleteRoomAttributes(keys, room_id, nullptr, [=](const std::string &roomID, const std::vector<std::string> &errorKeyList,const ZIMError &errorInfo){});
1
获取房间属性
注意
登录房间时,房间最新属性将通过 onRoomAttributesUpdated 回调返回,无需调用 queryRoomAllAttributes 。
示例代码
zim->queryRoomAllAttributes(room_id,[=](const std::string &roomID, const std::unordered_map<std::string, std::string> &roomAttributes,const ZIMError &errorInfo){});
1
房间属性组合操作
组合操作可以使用 beginRoomAttributesBatchOperation 和 endRoomAttributesBatchOperation 方法将同一房间中,多个不同操作合并为一个原子操作进行执行,通常用于连续操作时不想被其他用户操作插入执行的情况。
示例代码
std::unordered_map<std::string, std::string> roomAttributes;
std::vector<std::string> keys;
auto config = zim::ZIMRoomAttributesBatchOperationConfig{true, true, true};
zim_->BeginRoomAttributesBatchOperation(utf8_room_id, &config);
zim_->BeginRoomAttributesBatchOperation(room_id, &config);
zim->setRoomAttributes(roomAttributes, room_id, nullptr, [=](const std::string &roomID, const std::vector<std::string> &errorKeyList,const ZIMError &errorInfo){});
zim->deleteRoomAttributes(keys, room_id, nullptr, [=](const std::string &roomID, const std::vector<std::string> &errorKeyList,const ZIMError &errorInfo){});
zim->endRoomAttributesBatchOperation(room_id,[=](const std::string &roomID, const ZIMError &errorInfo){});
1