房间属性管理

---

功能简介

ZIM SDK 的房间属性功能，提供了可在指定房间中，设置自定义属性的能力。

通常可以应用在语音直播、聊天室等的属性同步、语聊房的麦位管理、以及狼人杀等卡牌类游戏中，记录用户的角色和牌局状态等场景中。

前提条件

在设置“房间属性”功能之前，请确保：

• 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID、AppSign。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考控制台的 服务配置 - 即时通讯 - 开通服务），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
• 已集成 ZIM SDK，详情请参考 快速开始 - 实现基本收发消息 的 “2 集成 SDK”。

实现流程

开发者需要在调用 createRoom 接口时，设置房间属性参数，创建并加入房间。

- (void)createRoom:(ZIMRoomInfo *)roomInfo
            config:(ZIMRoomAdvancedConfig *)config
          callback:(ZIMRoomCreatedCallback)callback;

参数说明

示例代码

// roomID 最大 128 字节的字符串。仅支持数字，英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'。
// roomName 最大 64 字节的字符串，无特殊字符限制。
ZIMRoomInfo *zimRoomInfo = [[ZIMRoomInfo alloc] init];        
//创建房间属性对象
ZIMRoomAdvancedConfig *config = [[ZIMRoomAdvancedConfig alloc] init];
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
NSString *myValue = @"room_info_value"
NSString *myKey = @"room_info";

[roomAttributes setObject:myValue forKey:myKey];

config.roomAttributes = roomAttributes;

[zim createRoom:zimRoomInfo config:config callback:^(ZIMRoomFullInfo * _Nonnull roomInfo, ZIMError * _Nonnull errorInfo) {}];

设置房间属性

每个房间中，设置的属性以 Key-Value 的形式存储。

• 当 Key 不存在时，设置房间属性表示增加属性。
• 当 key 已经存在时，设置房间属性表示更新已有属性的取值。

参数说明

示例代码

NSString *key = @"room_info";
NSString *value = @"room_info_value";
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
[roomAttributes setObject:value forKey:key];
ZIMRoomAttributesSetConfig *setConfig = [[ZIMRoomAttributesSetConfig alloc] init];
setConfig.isDeleteAfterOwnerLeft = true;
setConfig.isForce = false;
[zim setRoomAttributes:roomAttributes roomID:roomID config:setConfig callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

删除房间属性

通常开发者只能删除自己拥有的属性，也可以设置 “config” 中的 “isForce” 参数取值，删除他人创建的属性。

参数说明

示例代码

NSString *key = [NSString stringWithFormat:@"seat_%d",targetIndex];
NSMutableArray *keys = [[NSMutableArray alloc] init];
[keys addObject:key];
ZIMRoomAttributesDeleteConfig *config = [[ZIMRoomAttributesDeleteConfig alloc] init];
config.isForce = true;
[zim deleteRoomAttributesByKeys:keys roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

获取房间属性

参数说明

示例代码

[zim queryRoomAllAttributesByRoomID:roomID callback:^(NSString * _Nonnull roomID, NSDictionary<NSString *,NSString *> * _Nonnull roomAttributes, ZIMError * _Nonnull errorInfo) {}];

房间属性组合操作

组合操作可将同一房间中，多个不同操作合并为一个原子操作进行执行，通常用于连续操作时不想被其他用户操作插入执行的情况。

beginRoomAttributesBatchOperationWithRoomID 参数说明

endRoomAttributesBatchOperationWithRoomID 参数说明

示例代码

//组操作
NSMutableDictionary *roomAttributes = [[NSMutableDictionary alloc] init];
NSString *key = @"key";
NSString *value = @"value";
[roomAttributes setObject:value forKey:key];
//设置本次增加房间属性的操作配置
ZIMRoomAttributesSetConfig *config = [[ZIMRoomAttributesSetConfig alloc] init];
config.isForce = false;
config.isDeleteAfterOwnerLeft = true;
//删除房间属性相关配置
NSString *deleteKey = @"key";
NSMutableArray *keys = [[NSMutableArray alloc] init];
[keys addObject:deleteKey];
ZIMRoomAttributesDeleteConfig *deleteConfig = [[ZIMRoomAttributesDeleteConfig alloc] init];
//设置组操作
ZIMRoomAttributesBatchOperationConfig *setConfig = [[ZIMRoomAttributesBatchOperationConfig alloc] init];
setConfig.isDeleteAfterOwnerLeft = true;
setConfig.isForce = false;
setConfig.isUpdateOwner = true;
[zim beginRoomAttributesBatchOperationWithRoomID:roomID config:setConfig];
//修改房间属性

//先增
[zim setRoomAttributes:roomAttributes roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

//后删
[zim deleteRoomAttributesByKeys:keys roomID:roomID config:config callback:^(NSString * _Nonnull roomID, NSArray<NSString *> * _Nonnull errorKeys, ZIMError * _Nonnull errorInfo) {}];

//完成组合操作
[zim endRoomAttributesBatchOperationWithRoomID:roomID callback:^(NSString * _Nonnull roomID, ZIMError * _Nonnull errorInfo) {}];