tencent cloud

Tencent Real-Time Communication

Room Management (Android)

Download
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-06-15 15:14:30
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.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 = "test_room_001"
private val roomType = RoomType.STANDARD

fun createAndJoinRoom() {
// 1. Configure room creation parameters
// CreateRoomOptions defines basic room attributes and initial permissions
val options = CreateRoomOptions(
roomName = "Team Meeting Room", // Room display name
password = "", // Room password (optional)
// 2. Set initial permission controls
isAllCameraDisabled = false, // Allow member cameras
isAllMessageDisabled = false, // Allow member chat
isAllMicrophoneDisabled = false, // Allow member microphones
isAllScreenShareDisabled = false // Allow screen sharing
)

// 3. Create and join room
// Handles creation (if needed) and join logic automatically
RoomStore.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.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 = "test_room_001"
private val roomType = RoomType.STANDARD

fun joinRoom() {
// 1. Prepare join parameters
// joinRoom joins a known, active room
val roomPassword = "" // Room password; pass empty string or null if not set

// 2. Join room
// Checks room existence, user ban status, and password validity
RoomStore.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.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import io.trtc.tuikit.atomicxcore.api.CompletionHandler

fun 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-side
RoomStore.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.Log
import io.trtc.tuikit.atomicxcore.api.CompletionHandler
import io.trtc.tuikit.atomicxcore.api.room.RoomStore

fun 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 participants
RoomStore.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.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 = "test_room_001"

fun updateRoomInfo() {
// 1. Configure update parameters
// UpdateRoomOptions specifies which attributes to update
val options = UpdateRoomOptions(
roomName = "New Meeting Room Name" // Update room display name
)

// 2. Set modification flags
// modifyFlagList specifies fields to update; supports multiple flags
val modifyFlagList = listOf(UpdateRoomOptions.ModifyFlag.ROOM_NAME)

// 3. Update room info
// Submits update to server and syncs to all members
RoomStore.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.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 = "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 server
RoomStore.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.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) {

// Room event listener
private 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 listener
RoomStore.shared().addRoomListener(roomListener)
}

override fun onDetachedFromWindow() {
super.onDetachedFromWindow()
// Remove listener to prevent memory leaks
RoomStore.shared().removeRoomListener(roomListener)
}
}
Subscribe to RoomState property changes. For example, listen for changes in the current room information:
import android.util.Log
import io.trtc.tuikit.atomicxcore.api.room.RoomStore
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

// Subscribe to current room info updates
private 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.

Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan