RoomStore 专职负责 AtomicXCore 中的房间事务管理,提供从房间创建到解散的完整流程控制接口。通过 RoomStore 提供的接口(如获取及更新房间信息),可高效开发出一套成熟的房间管理体系。onRoomEnded 事件。RoomStore 相关的几个核心概念:核心概念 | 类型 | 核心职责与描述 |
struct | 代表房间信息的核心数据模型,封装了房间的完整信息和状态管理能力。 核心功能包括: 房间基本信息管理(房间 ID、名称、创建者)。 实时状态跟踪(参与者数量、房间状态、创建时间)。 房间调度功能(预约时间、参会者列表、提醒设置)。 权限控制(密码保护、设备管控、消息管理)。 | |
struct | 代表房间状态管理的核心数据结构,负责维护用户的房间相关状态信息。 核心属性: scheduledRoomList 存储了当前账号下所有预约的房间列表信息。scheduledRoomListCursor 则代表预约房间列表的分页快照。currentRoom 则代表当前所在房间的状态信息。 | |
enum | 代表房间动态的实时事件。主要事件分为三大类:预约房间事件,房间结束事件,房间呼叫事件。 | |
class | 这是与房间全生命周期相关的核心类。功能包含:获取预约房间列表快照、执行房间管理操作,并通过订阅其 roomEventPublisher 来接收实时动态事件。 |
CreateRoomOptions 来设置房间名称,房间密码。RoomStore 的 createAndJoinRoom 接口执行核心操作。import Foundationimport AtomicXCorefunc createAndJoinRoom() {// 1. 配置房间创建参数// CreateRoomOptions 定义房间的基础属性和初始权限设置var options = CreateRoomOptions()options.roomName = "团队会议室" // 房间显示名称options.password = "" // 房间密码(可选)// 2. 房间权限预设options.isAllCameraDisabled = false // 是否禁用所有成员摄像头options.isAllMessageDisabled = false // 是否禁言所有成员options.isAllMicrophoneDisabled = false // 是否静音所有成员options.isAllScreenShareDisabled = false // 是否禁止所有成员屏幕分享// 3. 创建并加入房间// 该方法会自动处理房间创建(如果不存在)和加入逻辑RoomStore.shared.createAndJoinRoom(roomID: "roomID", roomType: .standard, options: options) { result inswitch result {case .success():print("成功创建并加入房间")case .failure(let error):print("创建并加入房间失败 [错误码: \\(error.code)]: \\(error.message)")}}}
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型。 standard:标准房间,所有成员可自由音视频互动。 webinar:大型研讨会房间,区分嘉宾和观众角色,观众默认无上麦权限。 |
options | CreateRoomOptions | 是 | 创建房间配置对象。 详细用法请参考:CreateRoomOptions 结构体详细说明。 |
completion | CompletionClosure | 否 | 操作完成回调,用于返回创建和加入房间的结果。若创建失败则会返回错误码和错误信息。 |
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
isAllMicrophoneDisabled | Bool | 否 | 是否全员禁止打开麦克风。开启后,除房主/管理员外,普通参与者默认禁止打开麦克风。 true:禁止。 false:取消禁止 (默认值)。 |
isAllCameraDisabled | Bool | 否 | 是否全员禁止打开摄像头。开启后,除房主/管理员外,普通参与者默认禁止打开摄像头。 true:禁止。 false:取消禁止(默认值)。 |
isAllScreenShareDisabled | Bool | 否 | 是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。 true:禁止。 false:取消禁止(默认值)。 |
isAllMessageDisabled | Bool | 否 | 是否全员禁止发送聊天消息(禁言)。开启后,普通参与者无法在房间内发送文字消息。 true:禁止。 false:取消禁止(默认值)。 |
RoomStore 的 joinRoom 接口,即可加入房间,此时房间内其他参与者会收到参与者加入房间事件通知。import Foundationimport AtomicXCorefunc joinRoom() {// 1. 准备加入房间参数// joinRoom 适用于加入一个已知且正在进行的房间let roomPassword = "" // 房间密码,若房间未设置密码则传空字符串或 nil// 2. 调用 RoomStore 加入房间接口// 该操作会验证房间是否存在、用户是否被禁入以及密码是否正确RoomStore.shared.joinRoom(roomID: "roomID", roomType: .standard, password: roomPassword) { result inswitch result {case .success():print("加入房间成功")case .failure(let error):print("加入房间失败 [错误码: \\(error.code)]: \\(error.message)")}}}
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型 standard:标准房间,所有成员可自由音视频互动。 webinar:大型研讨会房间,区分嘉宾和观众角色,观众默认无上麦权限。 |
password | String | 是 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
completion | CompletionClosure | 否 | 操作完成回调,用于返回加入房间的结果。若创建失败则会返回错误码和错误信息。 |
RoomStore 的 leaveRoom 接口即可离开房间,此时房间内其他参与者都会收到参与者离开房间事件通知。import Foundationimport AtomicXCorefunc leaveRoom() {// 1. 业务逻辑说明// leaveRoom 接口用于普通成员或房主主动退出房间// 与 endRoom 不同,房主调用 leaveRoom 只会让自己离开,房间依然存在// 2. 调用 RoomStore 离开房间接口// 该操作会停止音视频流传输,并通知服务器将当前用户移出房间RoomStore.shared.leaveRoom { result inswitch result {case .success():print("离开房间成功")case .failure(let error):print("离开房间失败 [错误码: \\(error.code)]: \\(error.message)")}}}
RoomStore 的 endRoom 接口即可结束当前房间。结束房间后,房间内的所有参与者都会收到房间结束事件。import Foundationimport AtomicXCorefunc endRoom() {// 1. 业务逻辑说明// endRoom 接口用于永久解散当前房间// 注意:该操作通常仅限房主(Owner)执行,解散后所有成员将被强制退出// 2. 调用 RoomStore 解散房间接口// 该方法会向服务器发送解散指令,并通知所有在线参与者房间已结束RoomStore.shared.endRoom { result inswitch result {case .success():print("解散房间成功")case .failure(let error):print("解散房间失败 [错误码: \\(error.code)]: \\(error.message)")}}}
RoomStore 的 updateRoomInfo 接口即可更新房间信息。更新后房间内的参与者会收到房间状态变更通知。import Foundationimport AtomicXCorefunc updateRoomInfo() {// 1. 配置房间更新参数// UpdateRoomOptions 用于定义需要更新的房间属性var options = UpdateRoomOptions()options.roomName = "新的会议室名称" // 更新房间显示名称// 2. 设置修改标志位// ModifyFlag 用于指定具体要更新哪些字段var modifyFlag: UpdateRoomOptions.ModifyFlag = []modifyFlag.insert(.roomName) // 标记需要更新房间名称// 3. 调用 RoomStore 更新房间信息接口// 该方法会向服务器提交更新请求,并同步给所有房间成员RoomStore.shared.updateRoomInfo(roomID: "roomID", options: options, modifyFlag: modifyFlag) { result inswitch result {case .success():print("更新房间信息成功")case .failure(let error):print("更新房间信息失败 [错误码: \\(error.code)]: \\(error.message)")}}}
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
options | UpdateRoomOptions | 是 | 更新房间属性配置对象。 详细用法请参考:UpdateRoomOptions 结构体详细说明 |
modifyFlag | UpdateRoomOptions.ModifyFlag | 是 | 更新房间属性修改标志位。目前支持更新房间名称、房间密码。 详细用法请参考:UpdateRoomOptions.ModifyFlag 详细说明。 |
completion | CompletionClosure | 否 | 操作完成回调,用于返回更新房间信息的结果。若更新失败则会返回错误码和错误信息。 |
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
参数名 | 类型 | 必填 | 说明 |
roomName | UInt | 否 | 修改房间名称时的标识位。 当修改 UpdateRoomOptions 中的 roomName 后,需要同步设置 ModifyFlag 的 roomName 标识位。 |
password | UInt | 否 | 修改房间密码时的标识位。 当修改 UpdateRoomOptions 中的 password 后,需要同步设置 ModifyFlag 的 password 标识位。 |
RoomStore 的 getRoomInfo 接口即可获取到房间详细信息。import Foundationimport AtomicXCorefunc getRoomInfo() {// 1. 业务逻辑说明// getRoomInfo 接口用于获取指定房间的详细信息// 可以获取房间名称、创建者、参与者数量、权限设置等完整信息// 2. 调用 RoomStore 获取房间信息接口// 该操作会从服务器获取最新的房间状态和配置信息RoomStore.shared.getRoomInfo(roomID: "roomID") { result inswitch result {case .success(let roomInfo):print("获取房间信息成功,roomInfo: \\(roomInfo)")case .failure(let error):print("获取房间信息失败 [错误码: \\(error.code)]: \\(error.message)")}}}
RoomEvent 房间内的被动事件。以订阅房间结束事件为例,示例代码如下:import Foundationimport AtomicXCoreimport Combineprivate var cancellableSet = Set<AnyCancellable>()/// 设置房间事件监听器private func subscribeRoomEvent() {RoomStore.shared.roomEventPublisher.receive(on: DispatchQueue.main) // 确保在主线程处理 UI 逻辑.sink { event inswitch event {case .onRoomEnded(let roomInfo):print("当前所在房间已结束")default: break}}.store(in: &cancellableSet)}
RoomState 房间属性状态变化。以订阅当前所在房间信息变化为例,示例代码如下:import Foundationimport AtomicXCoreimport Combineprivate var cancellableSet = Set<AnyCancellable>()private func subscribeRoomState() {/// 设置当前房间状态监听器RoomStore.shared.state.subscribe(StatePublisherSelector(keyPath: \\.currentRoom)).receive(on: DispatchQueue.main) // 确保在主线程处理 UI 逻辑.sink { roomInfo inif let newRoomInfo = roomInfo {print("房间信息更新 新的房间信息: \\(newRoomInfo)")}}.store(in: &cancellableSet)}
Store/Component | 功能描述 | API 文档 |
RoomStore | 房间全生命周期管理:创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件(如房间解散,房间信息更新等)。 |
RoomInfo 中的参与人数(participantCount)是如何更新的?时机和频率是怎样的?participantCount 的更新并非总是实时的,其机制如下:RoomState 中的 currentRoom 观察到 participantCount 的变化。participantCount 是一个非常接近实时的高精度估算值,但在极端高并发场景下,它可能存在短暂的延迟或数据丢失。因此,我们建议您将其用于 UI 展示,而不应作为计费、统计等需要绝对精准场景的唯一依据。文档反馈