룸 관리
RoomStore is the central API for managing rooms in AtomicXCore, providing a full suite of lifecycle management interfaces—from creating and joining rooms to updating, dissolving, and retrieving room information. By integrating RoomStore’s interfaces, you can build a comprehensive and reliable room management system.
Core Features
Create and Join Room: Hosts can use this interface to create a room and immediately enter it.
Join Room: Participants can join an existing room using this interface.
Leave Room: Participants can exit a room they’ve joined.
End Room: Hosts can end the current room. If other participants are present, they will receive the
onRoomEnded event.Update Room Information: Hosts or administrators can update room details such as the room name or password.
Get Room Information: Retrieve detailed information for any room.
Core Concepts
Before you begin integration, review these key RoomStore concepts:
Core Concept | Type | Core Responsibilities & Description |
data class | Main data model for room details, encapsulating full room information and state. Key features: Manages basic room info (Room ID, name, creator). Tracks real-time status (participant count, room status, creation time). Supports scheduling (scheduled time, participant list, reminders). Controls permissions (password protection, device management, message management). | |
data class | Core state structure for user-related room information. Key properties: scheduledRoomList: All scheduled rooms for the current account.scheduledRoomListCursor: Pagination snapshot for scheduled rooms.currentRoom: State of the room currently joined. | |
abstract class | Handles real-time events for room dynamics, including room reservation, room end, and room call events. | |
abstract class | Core class for managing the entire room lifecycle. Functions include: retrieving reservation snapshots, executing room operations, and subscribing to RoomListener for real-time events. |
Implementation Steps
Step 1: Integrate Components
Follow the Integration Overview to integrate the AtomicXCore SDK. Make sure you have completed the Implement Login Logic before proceeding.
Step 2: Create and Join a Room
Implementation
1. Configure Room Initialization Parameters: Initialize
CreateRoomOptions to set the room name and password.2. Set Room Permissions: Configure global member permissions (mute all, disable cameras, etc.).
3. Create and Join Room: Use RoomStore’s
createAndJoinRoom interface to create and enter the room.Sample Code
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. Configure room creation parameters// CreateRoomOptions defines basic room attributes and initial permissionsval options = CreateRoomOptions(roomName = "Team Meeting Room", // Room display namepassword = "", // Room password (optional)// 2. Set initial permission controlsisAllCameraDisabled = false, // Allow member camerasisAllMessageDisabled = false, // Allow member chatisAllMicrophoneDisabled = false, // Allow member microphonesisAllScreenShareDisabled = false // Allow screen sharing)// 3. Create and join room// Handles creation (if needed) and join logic automaticallyRoomStore.shared().createAndJoinRoom(roomID, roomType, options, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room created and joined successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to create and join room [Error code: $code]: $desc")}})}
createAndJoinRoom Interface Parameter Details
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
roomType | RoomType | Yes | Room type: STANDARD: Standard room (default).WEBINAR: Large webinar room.Use STANDARD for multi-party meetings. |
options | CreateRoomOptions | Yes | Room creation configuration object. |
completion | CompletionHandler | No | Completion callback for creation/join result. Returns error code and message if creation fails. |
CreateRoomOptions Struct Documentation
Parameter Name | Type | Required | Description |
roomName | String | No | Room name (optional; defaults to empty string). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. Recommend 4–8 digits for easy mobile input. If set, other users must enter the password to join. Avoid storing sensitive information in plain text. |
isAllMicrophoneDisabled | Boolean | No | Disable microphones for all members. true: Disabled. false: Not disabled (default). Only owner/administrator can unmute; regular participants are muted by default. |
isAllCameraDisabled | Boolean | No | Disable cameras for all members. true: Disabled. false: Not disabled (default). Only owner/administrator can enable cameras; regular participants are disabled by default. |
isAllScreenShareDisabled | Boolean | No | Disable screen sharing for all members. true: Disabled. false: Not disabled (default). Only owner/administrator can share screens. |
isAllMessageDisabled | Boolean | No | Mute all members (disable chat messages). true: Disabled. false: Not disabled (default). Regular participants cannot send text messages in the room. |
Step 3: Join a Room
To join a room, participants call the
joinRoom interface on RoomStore. All other participants will receive a notification when someone joins.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. Prepare join parameters// joinRoom joins a known, active roomval roomPassword = "" // Room password; pass empty string or null if not set// 2. Join room// Checks room existence, user ban status, and password validityRoomStore.shared().joinRoom(roomID, roomType, roomPassword, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Joined room successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to join room [Error code: $code]: $desc")}})}
joinRoom Interface Parameter Details
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
roomType | RoomType | Yes | Room type: STANDARD: Standard room (default).WEBINAR: Large webinar room.Use STANDARD for large multi-party meetings. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. Recommend 4–8 digits for easy mobile input. If set, other users must enter the password to join. Avoid storing sensitive information in plain text. |
completion | CompletionHandler | No | Completion callback for join result. Returns error code and message if joining fails. |
Step 4: Leave a Room
To leave a room, call RoomStore’s
leaveRoom interface. All other participants will receive a notification when someone leaves.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerfun leaveRoom() {// 1. Business logic// leaveRoom is for members or hosts to voluntarily exit// If the host leaves, the room remains active// 2. Leave room// Stops audio/video streams and removes the user from the room server-sideRoomStore.shared().leaveRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Left room successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to leave room [Error code: $code]: $desc")}})}
Step 5: End a Room
Hosts can end a room using RoomStore’s
endRoom interface. All participants will receive a room-end event.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStorefun endRoom() {// 1. Business logic// endRoom permanently dissolves the current room// Typically restricted to the host; all members are forcibly exited// 2. End room// Sends dissolve command to server and notifies all online participantsRoomStore.shared().endRoom(object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room dissolved successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to dissolve room [Error code: $code]: $desc")}})}
Step 6: Update the Room Information
Hosts can update the room name or password with RoomStore’s
updateRoomInfo interface. All room participants will be notified of the change.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. Configure update parameters// UpdateRoomOptions specifies which attributes to updateval options = UpdateRoomOptions(roomName = "New Meeting Room Name" // Update room display name)// 2. Set modification flags// modifyFlagList specifies fields to update; supports multiple flagsval modifyFlagList = listOf(UpdateRoomOptions.ModifyFlag.ROOM_NAME)// 3. Update room info// Submits update to server and syncs to all membersRoomStore.shared().updateRoomInfo(roomID, options, modifyFlagList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Room information updated successfully")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to update room information [Error code: $code]: $desc")}})}
updateRoomInfo Interface Parameter Details
Parameter Name | Type | Required | Description |
roomID | String | Yes | Unique room identifier. Length: 0–48 bytes. Use only numbers, English letters (case-sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | UpdateRoomOptions | Yes | Room property update configuration object. See UpdateRoomOptions struct documentation for details. |
modifyFlagList | List | Yes | Room property modification flag. Currently supports updating room name and room password. See UpdateRoomOptions.ModifyFlag documentation for details. |
completion | CompletionHandler | No | Completion callback for update result. Returns error code and message if update fails. |
UpdateRoomOptions Struct Documentation
Parameter Name | Type | Required | Description |
roomName | String | No | Room name (optional; defaults to empty string). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password. Empty string means no password. Length: 0–32 bytes. Recommend 4–8 digits for easy mobile input. If set, other users must enter the password to join. Avoid storing sensitive information in plain text. |
UpdateRoomOptions.ModifyFlag Documentation
Parameter Name | Type | Required | Description |
ROOM_NAME | enum | No | Flag for modifying room name. When updating roomName in UpdateRoomOptions, set the ROOM_NAME flag. |
PASSWORD | enum | No | Flag for modifying room password. When updating password in UpdateRoomOptions, set the PASSWORD flag. |
Step 7: Retrieve the Room Information
After entering a room, call RoomStore’s
getRoomInfo interface to fetch detailed room information.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. Business logic// getRoomInfo retrieves detailed info for a specified room// Get room name, creator, participant count, permissions, and more// 2. Retrieve room info// Fetches latest room status and configuration from serverRoomStore.shared().getRoomInfo(roomID, object : GetRoomInfoCompletionHandler {override fun onSuccess(roomInfo: RoomInfo) {Log.d("Room", "Room information retrieved successfully, roomInfo: $roomInfo")}override fun onFailure(code: Int, desc: String) {Log.e("Room", "Failed to retrieve room information [Error code: $code]: $desc")}})}
Step 8: Listen for Real-Time Room Events and State Changes
Subscribe to room-level events. For example, to listen for the room end event:
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) {// Room event listenerprivate val roomListener = object : RoomListener() {override fun onRoomEnded(roomInfo: RoomInfo) {Log.d("Room", "The current room has ended")// Recommended: Close the current page and return to the previous screen}}override fun onAttachedToWindow() {super.onAttachedToWindow()// Add room event listenerRoomStore.shared().addRoomListener(roomListener)}override fun onDetachedFromWindow() {super.onDetachedFromWindow()// Remove listener to prevent memory leaksRoomStore.shared().removeRoomListener(roomListener)}}
Subscribe to RoomState property changes. For example, listen for changes in the current room information:
import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport kotlinx.coroutines.CoroutineScopeimport kotlinx.coroutines.Dispatchersimport kotlinx.coroutines.launch// Subscribe to current room info updatesprivate fun subscribeCurrentRoomState() {CoroutineScope(Dispatchers.Main).launch {RoomStore.shared().state.currentRoom.collect { roomInfo ->Log.d("Room", "Room information updated. New room info: $roomInfo")}}}
API Documentation
Store/Component | Feature Description | API Documentation |
RoomStore | Complete room lifecycle management: create and join, join, leave, end room, update and retrieve room information, room reservation, call members outside the room, listen for passive events such as room dissolution and info updates. |
FAQs
How is the participant count (participantCount) in RoomInfo updated? What are the timing and frequency?
participantCount updates are not strictly real-time. The mechanism is:Active entry/exit: When a user joins or leaves a room, the participant count notification is triggered instantly. You’ll see changes quickly in
currentRoom under RoomState.Abnormal disconnects: If a user disconnects due to network issues or app crashes, the system uses a heartbeat check. Only after missing heartbeats for 90 seconds will the user be considered offline and the count updated.
Update mechanism and rate control:
All participant count change notifications are sent as messages in the room, whether triggered instantly or delayed.
Each room is limited to 40 messages per second.
Important: In high-traffic situations (like a "live comments storm"), if message rates exceed 40/sec, participant count change messages may be dropped to prioritize core messages (such as live comments).
What does this mean for developers?
participantCount is a highly accurate, near real-time estimate. In rare cases with extremely high concurrency, brief delays or data loss may occur. We recommend using it for UI display only—not for billing, statistics, or scenarios requiring absolute precision.Contact Us
If you have questions or feedback during integration or usage, please email info_rtc@tencent.com.
