提交工单
咨询集成、功能及报价等问题
ZIM SDK 的房间属性功能,提供了可在指定房间中,设置自定义属性的能力。
通常可以应用在语音直播、聊天室等的属性同步、语聊房的麦位管理、以及狼人杀等卡牌类游戏中,记录用户的角色和牌局状态等场景中。
在设置“房间属性”功能之前,请确保:
开发者需要在调用 createRoom 接口时,设置房间属性参数,创建并加入房间。
public abstract void createRoom(ZIMRoomInfo roomInfo, ZIMRoomAdvancedConfig config, ZIMRoomCreatedCallback callback)
Key-Value
的方式进行存储。Key
的长度上限为 16 字节,Value
的长度上限为 1024 字节,所有属性的总长度不得超过 5120 字节。开发者如果需要提高属性上限,请联系 ZEGO 技术支持。参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
roomInfo | ZIMRoomInfo | 是 | 房间资料基础对象,包含房间 roomID、roomName 等信息。 |
config | ZIMRoomAdvancedConfig | 是 | 设置房间的高级属性配置。 |
callback | ZIMRoomCreatedCallback | 是 | 创建房间的回调。 |
// roomID 最大 128 字节的字符串。仅支持数字,英文字符 和 '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', '/', '\'。
// roomName 最大 64 字节的字符串,无特殊字符限制。
ZIMRoomInfo zimRoomInfo = new ZIMRoomInfo();
zimRoomInfo.roomID = roomID;
zimRoomInfo.roomName = "roomName" + roomID;
HashMap<String, String> hashMap = new HashMap<>();
hashMap.put("test1", "test2");
ZIMRoomAdvancedConfig zimRoomAdvancedInfo = new ZIMRoomAdvancedConfig();
zimRoomAdvancedInfo.roomAttributes = hashMap;
zim.createRoom(zimRoomInfo, zimRoomAdvancedInfo, new ZIMRoomCreatedCallback() {
@Override
public void onRoomCreated(ZIMRoomFullInfo roomInfo, ZIMError errorCode) {
assertSame(errorCode.code, SUCCESS);
}
});
每个房间中,设置的属性以 Key-Value
的形式存储。
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
roomAttributes | HashMap<String, String> | 是 | 房间属性存放的字典。 |
roomID | String | 是 | 标识需要查询房间属性的房间 ID。 |
config | ZIMRoomAttributesSetConfig | 否 | 属性对象配置,其中:
如果未对 config 进行设置,则默认不设置房间属性,且不更新房间属性拥有者及其它配置。 |
callback | ZIMRoomAttributesOperatedCallback | 是 | 房间属性操作的结果回调。 |
ZIMRoomAttributesSetConfig config = new ZIMRoomAttributesSetConfig();
config.isUpdateOwner = false;
config.isForce = false;
config.isDeleteAfterOwnerLeft = false;
zim.setRoomAttributes(hashMap, roomID, config, new ZIMRoomAttributesOperatedCallback() {
@Override
public void onRoomAttributesOperated(String roomID, ArrayList<String> errorKeys, ZIMError errorInfo) {
}
});
通常开发者只能删除自己拥有的属性,也可以设置 “config” 中的 “isForce” 参数取值,删除他人创建的属性。
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
keys | List |
是 | 需要删除房间属性的 Key。 |
roomID | String | 是 | 需要删除房间属性的房间 ID。 |
config | ZIMRoomAttributesDeleteConfig | 否 | 删除属性配置,其中 “isForce” 表示是否进行强制修改。 如果未对 config 进行设置,则默认不强制删除房间属性。 |
callback | ZIMRoomAttributesOperatedCallback | 是 | 删除房间属性操作的结果回调。 |
ArrayList<String> attributeList = new ArrayList<>();
attributeList.add("xxxx");
ZIMRoomAttributesDeleteConfig config = new ZIMRoomAttributesDeleteConfig();
config.isForce = true;
zim.deleteRoomAttributes(keys, roomID, config, new ZIMRoomAttributesOperatedCallback() {
@Override
public void onRoomAttributesOperated(String roomID, ArrayList<String> errorKeys, ZIMError errorInfo) {
}
});
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
roomID | String | 是 | 标识需要查询房间属性的房间 ID。 |
callback | ZIMRoomAttributesQueriedCallback | 是 | 查询房间属性操作的结果回调,查询成功时会返回当前房间的所有属性。 |
登录房间时,房间最新属性将通过 onRoomAttributesUpdated 回调返回,无需调用 queryRoomAllAttributes。
zim.queryRoomAllAttributes(roomID, new ZIMRoomAttributesQueriedCallback() {
@Override
public void onRoomAttributesQueried(String roomID, HashMap<String, String> roomAttributes, ZIMError errorInfo) {
}
});
组合操作可将同一房间中,多个不同操作合并为一个原子操作进行执行,通常用于连续操作时不想被其他用户操作插入执行的情况。
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
roomID | String | 是 | 需要设置房间属性的房间 ID。 |
config | ZIMRoomAttributesBatchOperationConfig | 否 | 属性配置,其中:
|
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
roomID | String | 是 | 需要设置房间属性的房间 ID。 |
callback | ZIMRoomAttributesBatchOperatedCallback | 否 | 执行房间属性操作的结果回调。 |
ZIMRoomAttributesBatchOperationConfig operationConfig = new ZIMRoomAttributesBatchOperationConfig();
operationConfig.isForce = false;
operationConfig.isDeleteAfterOwnerLeft = true;
zim.beginRoomAttributesBatchOperation(mRoomID, operationConfig);
zim.endRoomAttributesBatchOperation(roomID, new ZIMRoomAttributesBatchOperatedCallback() {
@Override
public void onRoomAttributesBatchOperated(String roomID, ZIMError errorInfo) {
}
});
联系我们
文档反馈