tencent cloud

实时音视频

预定房间(iOS)

Download
聚焦模式
字号
最后更新时间: 2026-06-15 15:14:30
RoomStoreAtomicXCore 的房间管理核心模块,涵盖了预定房间体系。本章节详细介绍了如何利用 RoomStore 高效完成预定房间功能的开发与接入。

核心功能

预定、取消预定房间:任何用户均可完成预定房间,取消预定房间功能。
更新预定房间信息:对已预定的房间进行房间信息更新,包含:房间名称,开始时间,结束时间。
获取预定房间列表:获取当前账户下所有预定的房间列表信息。
获取预定房间的参与成员列表:获取指定预定房间的参与成员列表信息。
添加、移除预定房间参与成员:对已预定的房间可以添加、移除参与成员。

核心概念

在开始集成之前,您可能需要通过下表了解一下 RoomStore 中与预订房间相关的几个核心概念:
核心概念
类型
核心职责与描述
enum
代表当前房间的状态,包含:
scheduled(预定状态)。
running(进行中)。
struct
代表预定房间的核心数据结构,包含:开始时间,结束时间,预定成员列表等。
RoomState
struct
代表房间状态管理的核心数据结构,负责维护用户的房间相关状态信息。
核心属性:
scheduledRoomList 存储了当前账号下所有预定的房间列表信息。
scheduledRoomListCursor 则代表预定房间列表的分页游标。
RoomEvent
enum
代表房间动态的实时事件。其中包含预定房间相关的事件。
RoomStore
class
这是与房间全生命周期相关的核心类。通过它,您可以主动发起预定房间,获取预定房间列表等功能,并通过订阅其 roomEventPublisher 来接收与预定房间相关的实时动态事件。

实现步骤

步骤1:组件集成

请参考 接入概览 集成 AtomicXCore SDK,并已完成 实现登录逻辑 部分接入。

步骤2:预定房间功能

一、预定房间

实现方式:
1. 配置预定房间初始化参数:初始化 ScheduleRoomOptions 预定房间配置项设置房间命名,房间密码、开始时间、结束时间、参与者、房间信息等。
2. 房间权限预设:设置房间内全场成员权限,例如全体静音,全体禁画等。
3. 预定房间:调用 RoomStore scheduleRoom 接口执行核心操作。
示例代码:
import AtomicXCore
import Foundation

// 预定房间
func scheduleRoom() {
let startTime = Int(Date().timeIntervalSince1970) + 60 * 15 // 计算预定时间:当前时间 + 15分钟后开始
let endTime = startTime + 60 * 30 // 计算结束时间:开始时间 + 30分钟(房间持续30分钟)
let reminderSeconds = 60 * 5 // 设置提醒时间:房间开始前5分钟提醒
// 创建预定房间选项配置
var options = ScheduleRoomOptions()
options.roomName = "房间名称"
options.scheduleStartTime = startTime
options.scheduleEndTime = endTime
options.reminderSecondsBeforeStart = reminderSeconds
options.scheduleAttendees = ["user01", "user02", "user03"] // 设置预定参与者列表(用户ID数组)
options.password = "房间密码" // 设置房间密码(可选,空字符串表示无密码)
options.isAllMicrophoneDisabled = false // 设置是否默认禁用所有参与者的麦克风(false = 允许开启麦克风)
options.isAllCameraDisabled = false // 设置是否默认禁用所有参与者的摄像头(false = 允许开启摄像头)
options.isAllScreenShareDisabled = false // 设置是否默认禁用所有参与者的屏幕共享(false = 允许屏幕共享)
options.isAllMessageDisabled = false // 设置是否默认禁用所有参与者的消息功能(false = 允许发送消息)
RoomStore.shared.scheduleRoom(roomID: "roomID", options: options) { result in
switch result {
case .success:
print("预定房间成功")
case .failure(let error):
print("预定房间失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}
scheduleRoom 接口参数详细说明
参数名
类型
必填
说明
roomID
String
字符串类型的房间唯一标识符。
限制长度为 0-48 字节。
建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。
options
ScheduleRoomOptions
创建房间配置对象。
completion
CompletionClosure
操作完成回调,用于返回预定房间的结果。若预定失败则会返回错误码和错误信息。
ScheduleRoomOptions 结构体详细说明
参数名
类型
必填
说明
roomName
String
房间名称,可以不设置,默认为空字符串。
限制长度为 0-60 字节。
支持中英文、数字、特殊字符。
password
String
房间密码,空字符串 "" 通常表示该房间不设密码。
限制长度为 0-32 字节。
推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。
scheduleStartTime
Int
预定的房间开始时间(Unix 时间戳,单位:秒)。
取值必须大于当前时间。
推荐设置为未来的整分时间。例如:1736164800(代表 2025-01-06 20:00:00)。
scheduleEndTime
Int
预定的房间结束时间(Unix 时间戳,单位:秒)。
取值必须大于 scheduleStartTime
建议根据预期时长设置。例如:scheduleStartTime + 3600(预定 1 小时时长的房间)。
reminderSecondsBeforeStart
Int
房间开始前的提醒时间(单位:秒)。用于系统触发开始提醒。
推荐设置为 300(5分钟)或 900(15分钟),用于在 App 端触发本地通知。
scheduleAttendees
[String]
预定参与者的用户 ID 列表,在预定房间时设置,系统将向这些用户发送预约邀请。
isAllMicrophoneDisabled
Bool
是否全员禁止打开麦克风。开启后,除房主/管理员外,普通参与者默认禁止打开麦克风。
true : 禁止。
false :取消禁止 (默认值)。
isAllCameraDisabled
Bool
是否全员禁止打开摄像头。开启后,除房主/管理员外,普通参与者默认禁止打开摄像头。
true : 禁止。
false :取消禁止(默认值)。
isAllScreenShareDisabled
Bool
是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。
true : 禁止。
false :取消禁止(默认值)。
isAllMessageDisabled
Bool
是否全员禁止发送聊天消息(禁言)。开启后,普通参与者无法在房间内发送文字消息。
true : 禁止。
false :取消禁止(默认值)。

二、取消房间预定

房间预定者调用 RoomStorecancelScheduledRoom 接口,实现取消预定房间功能。
import AtomicXCore
import Foundation

// 取消房间预定
func cancelScheduledRoom(roomID: String) {
RoomStore.shared.cancelScheduledRoom(roomID: roomID) { result in
switch result {
case .success:
print("取消预定房间成功")
case .failure(let error):
print("取消预定房间失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}

三、更新预定房间

房间预定者调用 RoomStoreupdateScheduledRoom 接口,实现更新预约房间名称开始时间结束时间
import AtomicXCore
import Foundation

// 更新预定房间
func updateScheduledRoom() {
let newStartTime = Int(Date().timeIntervalSince1970) + 60 * 30 // 计算预定时间:当前时间 + 30分钟后开始
let newEndTime = newStartTime + 60 * 45 // 计算结束时间:开始时间 + 45分钟(房间持续30分钟)
var options = ScheduleRoomOptions()
options.roomName = "房间名称"
options.scheduleStartTime = newStartTime
options.scheduleEndTime = newEndTime
var modifyFlag: ScheduleRoomOptions.ModifyFlag = []
modifyFlag.insert(.roomName)
modifyFlag.insert(.scheduleStartTime)
modifyFlag.insert(.scheduleEndTime)
RoomStore.shared.updateScheduledRoom(roomID: "roomID", options: options, modifyFlag: modifyFlag) { result in
switch result {
case .success:
print("更新预定房间成功")
case .failure(let error):
print("更新预定房间失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}
updateScheduledRoom 接口参数详细说明
参数名
类型
必填
说明
roomID
String
字符串类型的房间唯一标识符。
限制长度为 0-48 字节。
建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。
options
ScheduleRoomOptions
预定房间配置对象。
modifyFlag
ScheduleRoomOptions.ModifyFlag
更新房间属性修改标志位。目前支持更新房间名称开始时间结束时间。
completion
CompletionClosure
操作完成回调,用于返回更新预定房间的结果。若更新失败则会返回错误码和错误信息。

ScheduleRoomOptions.ModifyFlag 详细说明

参数名
类型
说明
roomName
UInt
修改预定房间名称时的标识位。
当修改 ScheduleRoomOptions 中的 roomName 后,需要同步设置 ModifyFlagroomName 标识位。
scheduleStartTime
UInt
修改预定房间开始时间时的标识位。
当修改 ScheduleRoomOptions 中的 scheduleStartTime 后,需要同步设置 ModifyFlagscheduleStartTime 标识位。
scheduleEndTime
UInt
修改预定房间结束时间时的标识位。
当修改 ScheduleRoomOptions 中的 scheduleEndTime 后,需要同步设置 ModifyFlagscheduleEndTime 标识位。

四、添加、删除参与成员

房间预定者调用 RoomStoreaddScheduledAttendees 或者 removeScheduledAttendees 接口,可以为已预约的房间内批量添加或移除预约参与者。
import AtomicXCore
import Foundation

// 添加参与成员
func addScheduledAttendees(roomID: String, userIDList: [String]) {
RoomStore.shared.addScheduledAttendees(roomID: roomID, userIDList: userIDList) { result in
guard let self = self else { return }
switch result {
case .success:
print("添加预定参与者成功")
case .failure(let error):
print("添加预定参与者失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}

// 移除参与成员
func removeScheduledAttendees(roomID: String, userIDList: [String]) {
RoomStore.shared.removeScheduledAttendees(roomID: roomID, userIDList: userIDList) { result in
switch result {
case .success:
print("移除预定参与者成功")
case .failure(let error):
print("移除预定参与者失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}

步骤3:获取预定房间列表

任意用户调用 RoomStoregetScheduledRoomList 接口,均可获取到自己账号下所有预约的房间列表信息。
import AtomicXCore
import Foundation

// 获取预定房间列表
func getScheduledRoomList(cursor: String? = nil) {
// cursor 为分页游标,首次调用时传入 null,获取第一页数据, 后续调用时传入上次返回的 nextCursor 值
RoomStore.shared.getScheduledRoomList(cursor: cursor) { result in
switch result {
case .success(let (roomList, nextCursor)):
print("获取预定房间列表成功")
case .failure(let error):
print("获取预定房间列表失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}

步骤4:获取指定预定房间的参与成员列表

任意用户调用 RoomStoregetScheduledAttendees 接口,可获取到指定预约房间的参与成员列表信息。

import AtomicXCore
import Foundation

// 获取预定房间的参与者列表
func getScheduledAttendees(roomID: String, cursor: String? = nil) {
// cursor 为分页游标,首次调用时传入 null,获取第一页数据, 后续调用时传入上次返回的 nextCursor 值
RoomStore.shared.getScheduledAttendees(roomID: roomID, cursor: cursor) { result in
switch result {
case .success(let (attendees, nextCursor)):
print("获取预定房间参与者列表成功")
case .failure(let error):
print("获取预定房间参与者列表失败: [错误码: \\(error.code)] \\(error.message)")
}
}
}

步骤5:监听预定房间实时事件及状态变化

订阅 RoomEvent 预定房间相关的被动事件,示例代码如下:
import AtomicXCore
import Foundation
import Combine

private var cancellableSet = Set<AnyCancellable>()

/// 订阅预定房间相关事件
private func subscribeScheduledRoomEvents() {
RoomStore.shared.roomEventPublisher
.receive(on: DispatchQueue.main)
.sink { event in
switch event {
case .onAddedToScheduledRoom(let roomInfo):
print("已被添加到预定房间 房间信息: \\(roomInfo)")
case .onRemovedFromScheduledRoom(let roomInfo, let operatorUser):
print("已被移除预定房间 房间信息: \\(roomInfo), 移除者: \\(operatorUser)")
case .onScheduledRoomCancelled(let roomInfo, let operatorUser):
print("预定房间被取消 房间信息: \\(roomInfo), 取消者: \\(operatorUser)")
case .onScheduledRoomStartingSoon(let roomInfo):
print("预定房间即将开始 房间信息: \\(roomInfo)")
default:
// 处理其他非预定房间相关事件
break
}
}
.store(in: &cancellableSet)
}
订阅 RoomState 预定房间列表状态变化,示例代码如下:
import AtomicXCore
import Foundation
import Combine

private var cancellableSet = Set<AnyCancellable>()

/// 订阅预定房间列表状态变化
private func subscribeScheduledRoomListState() {
RoomStore.shared.state.subscribe(StatePublisherSelector(keyPath: \\.scheduledRoomList))
.receive(on: DispatchQueue.main)
.sink { scheduledRoomList in
print("预定房间列表变化 房间列表信息: \\(scheduledRoomList)")
}
.store(in: &cancellableSet)
}

API 文档

Store/Component
功能描述
API 文档
RoomStore
房间全生命周期管理:创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件(例如房间解散,房间信息更新等)。

常见问题

当预约房间后,无法收到 RoomEventonScheduledRoomStartingSoon 事件。

如果您在预约房间后未收到即将开始的事件通知,请按照以下两个核心要点进行检查:
1. 检查提醒参数配置 (reminderSecondsBeforeStart)
触发机制:onScheduledRoomStartingSoon 事件的触发高度依赖于预约配置类 ScheduleRoomOptions 中的 reminderSecondsBeforeStart 属性。
默认行为:该属性的默认值为 0,代表“不开启提醒”。
解决建议:请确保在预约房间时明确设置该参数。该参数单位为,表示在房间开始前多少秒推送事件通知。
2. 验证预约时间逻辑
计算公式:系统触发提醒的前提是:预约开始时间 (scheduleStartTime) - 当前时间 > 提醒偏移量 (reminderSecondsBeforeStart)。
场景说明:如果您的房间开始时间设置得过近(例如 5 分钟后开始),而提醒时间设置得过大(例如设置 10 分钟前提醒),系统将无法捕捉到触发时机,从而导致事件丢失。
解决建议:请确保预约的开始时间距离当前时刻,大于您所设置的提醒秒数。

联系我们

如果您在接入或使用过程中有任何疑问或者建议,欢迎联系 info_rtc@tencent.com 提交反馈。

帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈