即时通信 IM 房间管理（Android）

一、核心功能

·创建并加入房间：房主通过调用该接口可以直接创建并进入房间。

·加入房间：参与者通过调用该接口可以直接进入已存在的房间。

·离开房间：参与者通过调用该接口可以退出已进入的房间。

·结束房间：房主通过调用该接口可以结束当前房间，如果房间内还有其他参与者，此时他们会收到 onRoomEnded 事件。

·更新房间信息：房主或管理员通过调用该接口可以更新房间信息，目前支持更新房间名称，房间密码。

·获取房间信息：通过调用该接口可以获取房间的详细信息。

二、核心概念

在开始集成之前，需要通过下表了解一下 RoomStore 相关的几个核心概念：

三、步骤1：组件集成

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

四、实现方式：

1. 配置房间初始化参数：初始化 CreateRoomOptions 设置置房间名称，房间密码。

2. 房间权限预设：设置房间内全场成员权限，例如全体静音，全体禁画等。

3. 创建并加入房间：调用 RoomStore 的 createAndJoinRoom 接口执行核心操作。

示例代码：

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 = "test_room_001"private val roomType = RoomType.STANDARDfun createAndJoinRoom() { // 1. 配置房间创建参数 // CreateRoomOptions 定义房间的基础属性和初始权限设置 val options = CreateRoomOptions( roomName = "团队会议室", // 房间显示名称 password = "", // 房间密码（可选） // 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 接口参数详细说明

CreateRoomOptions 结构体详细说明

五、步骤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 = "test_room_001"private val roomType = RoomType.STANDARDfun joinRoom() { // 1. 准备加入房间参数 // joinRoom 适用于加入一个已知且正在进行的房间 val roomPassword = "" // 房间密码，若房间未设置密码则传空字符串或 null // 2. 调用 RoomStore 加入房间接口 // 该操作会验证房间是否存在、用户是否被禁入以及密码是否正确 RoomStore.shared().joinRoom(roomID, roomType, roomPassword, object : CompletionHandler { override fun onSuccess() { Log.d("Room", "加入房间成功") } override fun onFailure(code: Int, desc: String) { Log.e("Room", "加入房间失败 [错误码: $code]: $desc") } })}

joinRoom 接口参数详细说明

六、步骤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 = "test_room_001"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 接口参数详细说明

UpdateRoomOptions 结构体详细说明

UpdateRoomOptions.ModifyFlag 详细说明

九、步骤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 = "test_room_001"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 文档

十二、RoomInfo 中的参与人数（participantCount）是如何更新的？时机和频率是怎样的？

participantCount 的更新并非总是实时的，其机制如下：

·主动进出房间：当用户主动加入或正常退出房间时，参与人数的变更通知会即时触发。你会很快在 RoomState 中的currentRoom观察到 participantCount 的变化。

·异常掉线：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。

·更新机制与频率控制：

·无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。

·房间内每秒的消息总量有上限，单房间消息频控是每秒 40 条消息。

·关键点：在“弹幕风暴”消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，人数变更的消息可能会被频控策略丢弃。

这对开发者意味着什么？

participantCount 是一个非常接近实时的高精度估算值，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议你将其用于 UI 展示，而不应作为计费、统计等需要绝对精准场景的唯一依据。

十三、联系我们

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