룸 예약
RoomStore is the core room management module in AtomicXCore, offering comprehensive support for scheduled meeting rooms. This section explains how to efficiently develop and integrate scheduled room features using RoomStore.Core Features
Schedule and Cancel Meeting Rooms: Any user can schedule or cancel a meeting room.
Update Scheduled Room Information: Update the information of existing scheduled rooms, including the room name, start time, and end time.
Retrieve Scheduled Room List: Retrieve a list of all scheduled rooms for the current account.
Retrieve Scheduled Room Participant List: Get the list of participants for a specific scheduled room.
Add or Remove Scheduled Room Participants: Add or remove participants from an existing scheduled room.
Core Concepts
Core concepts in
RoomStore are summarized in the table below:Core Concept | Type | Core Responsibilities & Description |
enum class | Current status of the room: SCHEDULED (scheduled).RUNNING (in progress). | |
data class | The data structure for scheduled rooms, including start time, end time, participant list, and more. | |
data class | Core data structure for room state management. Maintains user-related room state information. Key properties: scheduledRoomList: List of all scheduled rooms under the current account.scheduledRoomListCursor: Pagination cursor for the scheduled room list. | |
abstract class | Handles real-time events related to room activity, including scheduled room events. | |
abstract class | The class for managing the entire room lifecycle. Use it to schedule rooms, retrieve scheduled room lists, and subscribe to RoomListener for real-time scheduled room 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: Implement Scheduled Room Features
1. Scheduling a Room
Implementation Steps:
1. Set Initialization Parameters: Create a
ScheduleRoomOptions object to configure the room name, password, start time, end time, participant list, and other details.2. Set Room Permissions: Define global member permissions, such as mute all, disable all video, and other restrictions.
3. Schedule the Room: Call the
scheduleRoom method on RoomStore to complete the scheduling process.Example Code:
import io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.ScheduleRoomOptions// Schedule a roomfun scheduleRoom() {val startTime = (System.currentTimeMillis() / 1000) + 60 * 15 // Start time: now + 15 minutesval endTime = startTime + 60 * 30 // End time: start time + 30 minutesval reminderSeconds = 60 * 5 // Reminder: 5 minutes before start// Create room optionsval options = ScheduleRoomOptions(roomName = "Room Name",scheduleStartTime = startTime,scheduleEndTime = endTime,reminderSecondsBeforeStart = reminderSeconds,scheduleAttendees = listOf("user01", "user02", "user03"), // Participant user IDspassword = "Room Password", // Optional, empty string for no passwordisAllMicrophoneDisabled = false, // Default: allow microphonesisAllCameraDisabled = false, // Default: allow camerasisAllScreenShareDisabled = false, // Default: allow screen sharingisAllMessageDisabled = false // Default: allow chat messaging)RoomStore.shared().scheduleRoom("roomID", options, object : CompletionHandler {override fun onSuccess() {println("Room scheduled successfully")}override fun onFailure(code: Int, desc: String) {println("Failed to schedule room: [Error code: $code] $desc")}})}
scheduleRoom Method ParametersParameter | Type | Required | Description |
roomID | String | Yes | Unique string identifier for the room. Length: 0–48 bytes. Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | ScheduleRoomOptions | Yes | |
completion | CompletionHandler | No | Callback for operation completion. Returns result or error code/message if scheduling fails. |
ScheduleRoomOptions Struct DetailsParameter | Type | Required | Description |
roomName | String | No | Room name (optional, defaults to ""). Length: 0–60 bytes. Supports Chinese, English, numbers, and special characters. |
password | String | No | Room password ("" means no password). Length: 0–32 bytes. Recommend 4–8 digit numbers for easier input. If set, users must enter the password to join. Do not store sensitive info in plain text. |
scheduleStartTime | Long | Yes | Scheduled start time (Unix timestamp in seconds). Must be greater than the current time. We recommend aligning to a future minute. Example: 1736164800 (2025-01-06 20:00:00). |
scheduleEndTime | Long | Yes | Scheduled end time (Unix timestamp in seconds). Must be greater than scheduleStartTime.Set based on expected duration, e.g., scheduleStartTime + 3600 for one hour. |
reminderSecondsBeforeStart | Int | No | Reminder time before the scheduled start (seconds). Used for system-triggered notifications. Recommended: 300 (5 min) or 900 (15 min) for local app notifications. |
scheduleAttendees | List | No | List of participant user IDs. The system will send invitations to these users. For details, see retrieving the participant list for scheduled rooms. |
isAllMicrophoneDisabled | Boolean | No | Whether to mute all participants by default. true: Disabled. false: Not disabled (default). |
isAllCameraDisabled | Boolean | No | Whether to disable all participant cameras by default. true: Disabled. false: Not disabled (default). |
isAllScreenShareDisabled | Boolean | No | Whether to disable screen sharing for all participants. true: Disabled. false: Not disabled (default). |
isAllMessageDisabled | Boolean | No | Whether to mute chat messages for all participants. true: Disabled. false: Not disabled (default). |
2. Cancel a Scheduled Room
The room scheduler can call
RoomStore.cancelScheduledRoom to cancel a scheduled room.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// Cancel a scheduled roomfun cancelScheduledRoom(roomID: String) {RoomStore.shared().cancelScheduledRoom(roomID, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Successfully canceled scheduled room")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to cancel scheduled room: [Error code: $code] $desc")}})}
3. Update a Scheduled Room
The room scheduler can use
RoomStore.updateScheduledRoom to update the room name, start time, and end time for a scheduled room.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.ScheduleRoomOptions// Update a scheduled roomfun updateScheduledRoom() {val newStartTime = (System.currentTimeMillis() / 1000) + 60 * 30 // Start: now + 30 minutesval newEndTime = newStartTime + 60 * 45 // End: start + 45 minutesval options = ScheduleRoomOptions(roomName = "Room Name",scheduleStartTime = newStartTime,scheduleEndTime = newEndTime)val modifyFlagList = listOf(ScheduleRoomOptions.ModifyFlag.ROOM_NAME,ScheduleRoomOptions.ModifyFlag.SCHEDULE_START_TIME,ScheduleRoomOptions.ModifyFlag.SCHEDULE_END_TIME)RoomStore.shared().updateScheduledRoom("roomID", options, modifyFlagList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Successfully updated scheduled room")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to update scheduled room: [Error code: $code] $desc")}})}
updateScheduledRoom ParametersParameter | Type | Required | Description |
roomID | String | Yes | Unique string identifier for the room. Length: 0–48 bytes. Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
options | ScheduleRoomOptions | Yes | Configuration object for the scheduled room. See details in ScheduleRoomOptions struct. |
modifyFlagList | List<ScheduleRoomOptions.ModifyFlag> | Yes | Flags specifying which room properties to update. Can update room name, start time, and end time. See ModifyFlag documentation. |
completion | CompletionHandler | No | Callback for completion. Returns result or error code/message if update fails. |
ScheduleRoomOptions.ModifyFlag DetailsParameter | Type | Description |
ROOM_NAME | enum | Use this flag when updating the scheduled room name. You must also set the roomName field in ScheduleRoomOptions. |
SCHEDULE_START_TIME | enum | Use this flag when updating the scheduled room start time. You must also set the scheduleStartTime field in ScheduleRoomOptions. |
SCHEDULE_END_TIME | enum | Use this flag when updating the scheduled room end time. You must also set the scheduleEndTime field in ScheduleRoomOptions. |
4. Add or Remove Participants
To add or remove participants in a scheduled room, use
RoomStore.addScheduledAttendees or RoomStore.removeScheduledAttendees.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// Add scheduled participantsfun addScheduledAttendees(roomID: String, userIDList: List<String>) {RoomStore.shared().addScheduledAttendees(roomID, userIDList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Successfully added scheduled participants")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to add scheduled participants: [Error code: $code] $desc")}})}// Remove scheduled participantsfun removeScheduledAttendees(roomID: String, userIDList: List<String>) {RoomStore.shared().removeScheduledAttendees(roomID, userIDList, object : CompletionHandler {override fun onSuccess() {Log.d("Room", "Successfully removed scheduled participants")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to remove scheduled participants: [Error code: $code] $desc")}})}
Step 3: Retrieve the Scheduled Room List
Use
RoomStore.getScheduledRoomList to get all scheduled rooms for your account.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.ListResultCompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// Get scheduled room listfun getScheduledRoomList(cursor: String? = null) {// Use null for the first page; use the previous nextCursor for subsequent pagesRoomStore.shared().getScheduledRoomList(cursor, object : ListResultCompletionHandler<RoomInfo> {override fun onSuccess(result: List<RoomInfo>, cursor: String) {Log.d("Room", "Successfully retrieved scheduled room list")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to retrieve scheduled room list: [Error code: $code] $desc")}})}
Step 4: Retrieve the Participant List for a Scheduled Room
Use
RoomStore.getScheduledAttendees to retrieve participants for a specific scheduled room.import android.util.Logimport io.trtc.tuikit.atomicxcore.api.ListResultCompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomUser// Get participant list for a scheduled roomfun getScheduledAttendees(roomID: String, cursor: String? = null) {// Use null for the first page; use the previous nextCursor for subsequent pagesRoomStore.shared().getScheduledAttendees(roomID, cursor, object : ListResultCompletionHandler<RoomUser> {override fun onSuccess(result: List<RoomUser>, cursor: String) {Log.d("Room", "Successfully retrieved scheduled room participant list")}override fun onFailure(code: Int, desc: String) {Log.d("Room", "Failed to retrieve scheduled room participant list: [Error code: $code] $desc")}})}
Step 5: Subscribe to Real-Time Events and State Changes
Subscribe to scheduled room events with
RoomListener. Example:import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.RoomListenerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomUser/*** Subscribe to scheduled room events*/fun subscribeScheduledRoomEvents() {val listener = object : RoomListener() {override fun onAddedToScheduledRoom(roomInfo: RoomInfo) {Log.d("Room", "Added to scheduled room. Room info: $roomInfo")}override fun onRemovedFromScheduledRoom(roomInfo: RoomInfo, operator: RoomUser) {Log.d("Room", "Removed from scheduled room. Room info: $roomInfo, Removed by: $operator")}override fun onScheduledRoomCancelled(roomInfo: RoomInfo, operator: RoomUser) {Log.d("Room", "Scheduled room cancelled. Room info: $roomInfo, Cancelled by: $operator")}override fun onScheduledRoomStartingSoon(roomInfo: RoomInfo) {Log.d("Room", "Scheduled room starting soon. Room info: $roomInfo")}// Override other event callbacks as needed}RoomStore.shared().addRoomListener(listener)}
Subscribe to scheduled room list state changes with
RoomState. Example:import android.util.Logimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport kotlinx.coroutines.CoroutineScopeimport kotlinx.coroutines.Dispatchersimport kotlinx.coroutines.launch// Subscribe to scheduled room list state changesprivate fun subscribeParticipantState() {CoroutineScope(Dispatchers.Main).launch {RoomStore.shared().state.scheduledRoomList.collect { scheduledRoomList ->Log.d("Room", "Scheduled room list changed. Room list info: $scheduledRoomList")}}}
API Documentation
Store/Component | Feature Description | API Documentation |
RoomStore | Complete room lifecycle management: create & join / join / leave / end room / update & retrieve room info / schedule rooms / call out-of-room members / listen for in-room passive events (such as room dissolved, room info updated, etc.). |
FAQs
Why am I not receiving the onScheduledRoomStartingSoon event from RoomListener after scheduling a room?
If you are not receiving the upcoming event notification after scheduling a room, check the following:
1. Verify Reminder Parameter Configuration (
reminderSecondsBeforeStart)Trigger Mechanism: The
onScheduledRoomStartingSoon event is triggered based on the reminderSecondsBeforeStart property set in ScheduleRoomOptions.Default Value: The default is 0, which means reminders are disabled.
Solution: Set this parameter explicitly when scheduling a room. The value is in seconds and determines how long before the room starts the notification is sent.
2. Check Scheduled Time Logic
Calculation: The reminder triggers only if: scheduled start time (
scheduleStartTime) - current time > reminder offset (reminderSecondsBeforeStart).Edge Case: If the room is scheduled to start very soon (e.g., in 5 minutes) but the reminder is set for 10 minutes before start, the system cannot send the notification, and the event will be missed.
Solution: Ensure the scheduled start time is sufficiently further in the future than the reminder interval you've set.
Contact Us
For questions or feedback during integration or usage, contact info_rtc@tencent.com.
