RoomStore 专职负责 AtomicXCore 中的房间事务管理,提供从研讨会房间创建到解散的完整流程控制接口。通过 RoomStore 提供的接口(例如获取及更新房间信息),可高效开发出一套成熟的房间管理体系。核心功能
创建并加入房间:房主通过调用该接口可以直接创建并进入房间。
加入房间:成员通过调用该接口可以直接进入已存在的房间。
离开房间:成员通过调用该接口可以退出已进入的房间。
结束房间:房主通过调用该接口可以结束当前房间,如果房间内还有其他成员,此时他们会收到
onRoomEnded 事件。更新房间信息:房主或管理员通过调用该接口可以更新房间信息,目前支持更新房间名称。
获取房间信息:通过调用该接口可以获取房间的详细信息。
核心概念
在开始集成之前,需要通过下表了解一下
RoomStore 相关的几个核心概念:核心概念 | 类型 | 核心职责与描述 |
data class | 代表房间信息的核心数据模型,封装了房间的完整信息和状态管理能力。 核心功能包括: 房间基本信息管理(房间 ID、名称、创建者)。 实时状态跟踪(成员数量、房间状态、创建时间)。 权限控制(设备管控、消息管理)。 | |
data class | 代表房间状态管理的核心数据结构,负责维护用户的房间相关状态信息。 核心属性: currentRoom 则代表当前所在房间的状态信息。 | |
abstract class | 代表房间动态的实时事件。 | |
abstract class | 这是与房间全生命周期相关的核心类。功能包含:执行房间管理操作,并通过订阅其 RoomListener 来接收实时动态事件。 |
实现步骤
步骤1:组件集成
步骤2:主持人创建并加入研讨会房间
实现方式:
1. 配置房间初始化参数:初始化
CreateRoomOptions 设置房间名称等。2. 房间权限和成员管理配置信息预设:设置房间内全场成员权限,例如全体静音,全体禁画等。
3. 创建并加入房间:调用
RoomStore 的 createAndJoinRoom 接口执行核心操作。注意:
创建房间时指定的 roomId 建议由业务后台生成并下发,以确保房间 Id 在全局应用中的唯一性与稳定性。
建议研讨会房间 Id 统一使用
webinar_ 作为前缀,以便与标准会议房间区分。示例代码:
import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.CreateRoomOptionsimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomTypeprivate val roomID = "webinar_123456"private val roomType = RoomType.WEBINARfun createAndJoinRoom() {// 1. 配置房间创建参数// CreateRoomOptions 定义房间的基础属性和成员管理配置信息val options = CreateRoomOptions(roomName = "团队会议室", // 房间显示名称// 2. 设置房间初始权限控制isAllCameraDisabled = false, // 是否禁用所有成员摄像头isAllMessageDisabled = false, // 是否禁言所有成员isAllMicrophoneDisabled = false, // 是否静音所有成员isAllScreenShareDisabled = false // 是否禁止所有成员屏幕分享)// 3. 调用 RoomStore 创建并加入房间接口// 该方法会自动处理房间创建(如果不存在)和加入逻辑RoomStore.shared().createAndJoinRoom(roomID, roomType, options, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "成功创建并加入房间")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "创建并加入房间失败 [错误码: $code]: $desc")}})}
说明:
createAndJoinRoom 接口参数详细说明
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型。 STANDARD:标准房间。WEBINAR:大型研讨会房间。研讨会场景这里填写 WEBINAR 房间类型。 |
options | CreateRoomOptions | 是 | 创建房间配置对象。 详细用法请参考:CreateRoomOptions 结构体详细说明 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回创建和加入房间的结果。若创建失败则会返回错误码和错误信息。 |
CreateRoomOptions 结构体详细说明
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
isAllMicrophoneDisabled | Boolean | 否 | 是否全员禁止打开麦克风。开启后,除房主/管理员外,嘉宾默认禁止打开麦克风。 true : 禁止。 false :取消禁止 (默认值)。 |
isAllCameraDisabled | Boolean | 否 | 是否全员禁止打开摄像头。开启后,除房主/管理员外,嘉宾默认禁止打开摄像头。 true : 禁止。 false :取消禁止(默认值)。 |
isAllScreenShareDisabled | Boolean | 否 | 是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享。 true : 禁止。 false :取消禁止(默认值)。 |
isAllMessageDisabled | Boolean | 否 | 是否全员禁止发送聊天消息(禁言)。开启后,成员无法在房间内发送文字消息。 true : 禁止。 false :取消禁止(默认值)。 |
步骤3:观众加入研讨会房间
观众需要加入房间时,调用
RoomStore 的 joinRoom 接口,即可加入房间。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomTypeprivate val roomID = "webinar_123456"private val roomType = RoomType.WEBINARfun joinRoom() {// 1. 准备加入房间参数// joinRoom 适用于加入一个已知且正在进行的房间// 2. 调用 RoomStore 加入房间接口RoomStore.shared().joinRoom(roomID, roomType, completion = object : CompletionHandler {override fun onSuccess() {Log.d("Room", "加入房间成功")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "加入房间失败 [错误码: $code]: $desc")}})}
说明:
用户加入房间后,默认处于静默旁听状态,无法主动开启麦克风和摄像头。观众可以通过举手申请,经主持人审批后成为嘉宾,获得开启麦克风的权限,身份切换能力由
RoomParticipantState 提供,请参考 成员管理。joinRoom 接口参数详细说明
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型。 STANDARD:标准房间。WEBINAR:大型研讨会房间。研讨会场景这里填写 WEBINAR 房间类型。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回加入房间的结果。若加入房间失败则会返回错误码和错误信息。 |
步骤4:离开房间
当成员要离开房间时,通过调用
RoomStore 的 leaveRoom 接口即可离开房间。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerfun leaveRoom() {// 1. 业务逻辑说明// leaveRoom 接口用于普通成员或房主主动退出房间// 与 endRoom 不同,房主调用 leaveRoom 只会让自己离开,房间依然存在// 2. 调用 RoomStore 离开房间接口// 该操作会停止音视频流传输,并通知服务器将当前用户移出房间RoomStore.shared().leaveRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "离开房间成功")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "离开房间失败 [错误码: $code]: $desc")}})}
步骤5:结束房间
当房主期望结束房间时,调用
RoomStore 的 endRoom 接口即可结束当前房间。结束房间后,房间内的所有成员都会收到房间结束事件。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStorefun endRoom() {// 1. 业务逻辑说明// endRoom 接口用于永久解散当前房间// 注意:该操作通常仅限房主(Owner)执行,解散后所有成员将被强制退出// 2. 调用 RoomStore 解散房间接口// 该方法会向服务器发送解散指令,并通知所有在线成员房间已结束RoomStore.shared().endRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "解散房间成功")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "解散房间失败 [错误码: $code]: $desc")}})}
步骤6:更新房间信息
当房主期望更新房间名称时,调用
RoomStore 的 updateRoomInfo 接口即可更新房间信息。更新后房间内的成员会收到房间状态变更通知。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.UpdateRoomOptionsimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerprivate val roomID = "webinar_123456"fun updateRoomInfo() {// 1. 配置房间更新参数// UpdateRoomOptions 用于定义需要更新的房间属性val options = UpdateRoomOptions(roomName = "新的研讨会名称" // 更新房间显示名称)// 2. 设置修改标志位// modifyFlagList 用于指定具体要更新哪些字段,支持组合多个标志val modifyFlagList = listOf(UpdateRoomOptions.ModifyFlag.ROOM_NAME)// 3. 调用 RoomStore 更新房间信息接口// 该方法会向服务器提交更新请求,并同步给所有房间成员RoomStore.shared().updateRoomInfo(roomID, options, modifyFlagList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "更新房间信息成功")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "更新房间信息失败 [错误码: $code]: $desc")}})}
updateRoomInfo 接口参数详细说明
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
options | UpdateRoomOptions | 是 | 更新房间属性配置对象。 详细用法请参考:UpdateRoomOptions 结构体详细说明 |
modifyFlagList | List<UpdateRoomOptions.ModifyFlag> | 是 | 更新房间属性修改标志位。目前研讨会房间支持更新房间名称。 详细用法请参考:UpdateRoomOptions.ModifyFlag 详细说明。 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回更新房间信息的结果。若更新失败则会返回错误码和错误信息。 |
UpdateRoomOptions 结构体详细说明
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
UpdateRoomOptions.ModifyFlag 详细说明
参数名 | 类型 | 必填 | 说明 |
ROOM_NAME | enum | 否 | 修改房间名称时的标识位。 当修改 UpdateRoomOptions 中的 roomName 后,需要同步设置 ModifyFlag 的ROOM_NAME 标识位。 |
PASSWORD | enum | 否 | 修改房间密码时的标识位。 当修改 UpdateRoomOptions 中的 password 后,需要同步设置 ModifyFlag 的PASSWORD 标识位。研讨会场景暂时不支持密码功能。 |
步骤7:获取房间信息
进入房间成功后调用
RoomStore 的 getRoomInfo 接口即可获取到房间详细信息。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.GetRoomInfoCompletionHandlerprivate val roomID = "webinar_123456"fun getRoomInfo() {// 1. 业务逻辑说明// getRoomInfo 接口用于获取指定房间的详细信息// 可以获取房间名称、创建者、权限设置等完整信息// 2. 调用 RoomStore 获取房间信息接口// 该操作会从服务器获取最新的房间状态和配置信息RoomStore.shared().getRoomInfo(roomID, object : GetRoomInfoCompletionHandler {override fun onSuccess(roomInfo: RoomInfo) {Log.d("Room", "获取房间信息成功,roomInfo: $roomInfo")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "获取房间信息失败 [错误码: $code]: $desc")}})}
步骤8:监听房间实时事件及状态变化
订阅房间内的被动事件。以订阅房间结束事件为例,示例代码如下:
import android.content.Contextimport android.util.AttributeSetimport android.util.Logimport android.widget.FrameLayoutimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.RoomListenerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreclass RoomMainView @JvmOverloads constructor(context: Context,attrs: AttributeSet? = null,defStyleAttr: Int = 0) : FrameLayout(context, attrs, defStyleAttr) {// 房间事件监听器private val roomListener = object : RoomListener() {override fun onRoomEnded(roomInfo: RoomInfo) {Log.d("Room", "当前所在房间已结束")// 建议操作:关闭当前页面,返回上一级}}override fun onAttachedToWindow() {super.onAttachedToWindow()// 添加房间事件监听器RoomStore.shared().addRoomListener(roomListener)}override fun onDetachedFromWindow() {super.onDetachedFromWindow()// 移除监听器,防止内存泄漏RoomStore.shared().removeRoomListener(roomListener)}}
订阅
RoomState 房间属性状态变化。以订阅当前所在房间信息变化为例,示例代码如下:import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport kotlinx.coroutines.CoroutineScopeimport kotlinx.coroutines.Dispatchersimport kotlinx.coroutines.launch// 订阅当前所在房间信息变化private fun subscribeCurrentRoomState() {CoroutineScope(Dispatchers.Main).launch {RoomStore.shared().state.currentRoom.collect { roomInfo ->Log.d("Room", "房间信息更新 新的房间信息: $roomInfo")}}}
API 文档
Store/Component | 功能描述 | API 文档 |
RoomStore | 房间全生命周期管理:创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 监听房间内被动事件(例如房间解散,房间信息更新等)。 |
常见问题
研讨会房间是否存在自动解散机制?
有用户进入过研讨会房间后,房间持续空置超过一定时长(默认 30 分钟)且无人进房,触发自动解散。
房主调用接口离开房间后,持续超过一定时长(默认 10 分钟)未重新进房,触发自动解散。该时长支持调整,配置区间为 [2 分钟,12 小时]。
房主因心跳超时掉线后,持续超过一定时长(默认 10 分钟)未恢复心跳进房,触发自动解散。该时长支持调整,配置区间为 [2 分钟,12 小时]。
房间内已经没有用户但房间未被解散,是否会产生费用消耗?
不会。无用户且未解散的房间仅占用套餐直播间数量,不产生分钟数消耗及额外费用。