房间管理(Android)

最近更新时间:2026-05-06 20:41:44

我的收藏
RoomStore 专职负责 AtomicXCore 中的房间事务管理,提供从研讨会房间创建到解散的完整流程控制接口。通过 RoomStore 提供的接口(例如获取及更新房间信息),可高效开发出一套成熟的房间管理体系。

核心功能

创建并加入房间:房主通过调用该接口可以直接创建并进入房间。
加入房间:成员通过调用该接口可以直接进入已存在的房间。
离开房间:成员通过调用该接口可以退出已进入的房间。
结束房间:房主通过调用该接口可以结束当前房间,如果房间内还有其他成员,此时他们会收到 onRoomEnded 事件。
更新房间信息:房主或管理员通过调用该接口可以更新房间信息,目前支持更新房间名称。
获取房间信息:通过调用该接口可以获取房间的详细信息。

核心概念

在开始集成之前,需要通过下表了解一下 RoomStore 相关的几个核心概念:
核心概念
类型
核心职责与描述
RoomInfo
data class
代表房间信息的核心数据模型,封装了房间的完整信息和状态管理能力。
核心功能包括:
房间基本信息管理(房间 ID、名称、创建者)。
实时状态跟踪(成员数量、房间状态、创建时间)。
权限控制(设备管控、消息管理)。
RoomState
data class
代表房间状态管理的核心数据结构,负责维护用户的房间相关状态信息。
核心属性:
currentRoom 则代表当前所在房间的状态信息。
abstract class
代表房间动态的实时事件。
RoomStore
abstract class
这是与房间全生命周期相关的核心类。功能包含:执行房间管理操作,并通过订阅其 RoomListener 来接收实时动态事件。

实现步骤

步骤1:组件集成

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

步骤2:主持人创建并加入研讨会房间

实现方式:

1. 配置房间初始化参数:初始化 CreateRoomOptions 设置房间名称等。
2. 房间权限和成员管理配置信息预设:设置房间内全场成员权限,例如全体静音,全体禁画等。
3. 创建并加入房间:调用 RoomStorecreateAndJoinRoom 接口执行核心操作。
注意:
创建房间时指定的 roomId 建议由业务后台生成并下发,以确保房间 Id 在全局应用中的唯一性与稳定性。
建议研讨会房间 Id 统一使用 webinar_ 作为前缀,以便与标准会议房间区分。
示例代码:

import android.util.Log
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.room.CreateRoomOptions
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.room.RoomType

private val roomID = "webinar_123456"
private val roomType = RoomType.WEBINAR

fun 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:观众加入研讨会房间

观众需要加入房间时,调用 RoomStorejoinRoom 接口,即可加入房间。
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.room.RoomType

private val roomID = "webinar_123456"
private val roomType = RoomType.WEBINAR

fun 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:离开房间

当成员要离开房间时,通过调用 RoomStoreleaveRoom 接口即可离开房间。
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.CompletionHandler

fun 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:结束房间

当房主期望结束房间时,调用 RoomStoreendRoom 接口即可结束当前房间。结束房间后,房间内的所有成员都会收到房间结束事件。
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.room.RoomStore

fun 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")
}
})
}
说明:
如果房主离开房间但未调用 endRoom,房间将继续存在,直到满足自动回收条件(默认 10 分钟,支持后台配置)。
与标准会议不同,研讨会房间暂不支持转移房主能力。

步骤6:更新房间信息

当房主期望更新房间名称时,调用 RoomStoreupdateRoomInfo 接口即可更新房间信息。更新后房间内的成员会收到房间状态变更通知。
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.room.UpdateRoomOptions
import io.trtc.tuikit.atomicxcore.api.CompletionHandler

private 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>
更新房间属性修改标志位。目前研讨会房间支持更新房间名称
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:获取房间信息

进入房间成功后调用 RoomStoregetRoomInfo 接口即可获取到房间详细信息。
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.room.RoomInfo
import io.trtc.tuikit.atomicxcore.api.room.GetRoomInfoCompletionHandler

private 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.Context
import android.util.AttributeSet
import android.util.Log
import android.widget.FrameLayout
import io.trtc.tuikit.atomicxcore.api.room.RoomInfo
import io.trtc.tuikit.atomicxcore.api.room.RoomListener
import io.trtc.tuikit.atomicxcore.api.room.RoomStore

class 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.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import 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
房间全生命周期管理:创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 监听房间内被动事件(例如房间解散,房间信息更新等)。

常见问题

研讨会房间是否存在自动解散机制?

是的,研讨会房间在以下三种情况会触发自动解散逻辑。自动解散的开启条件和等待时长均支持按 sdkAppId 维度配置,如需调整请联系商务或 提交工单 进行变更。
有用户进入过研讨会房间后,房间持续空置超过一定时长(默认 30 分钟)且无人进房,触发自动解散。
房主调用接口离开房间后,持续超过一定时长(默认 10 分钟)未重新进房,触发自动解散。该时长支持调整,配置区间为 [2 分钟,12 小时]。
房主因心跳超时掉线后,持续超过一定时长(默认 10 分钟)未恢复心跳进房,触发自动解散。该时长支持调整,配置区间为 [2 分钟,12 小时]。

房间内已经没有用户但房间未被解散,是否会产生费用消耗?

不会。无用户且未解散的房间仅占用套餐直播间数量,不产生分钟数消耗及额外费用。

最多支持同时存在多少个研讨会房间?

同时存在的研讨会房间数量上限与您的套餐包相关,具体请查看 TUILiveKit 套餐包说明

最多支持多少人同时加入房间?

单个研讨会房间的人数上限与您的套餐包相关,具体请查看 TUILiveKit 套餐包说明

联系我们

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