@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/roomkit/core-sdk/android/schedule-room.md

@@ -0,0 +1,340 @@
+`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 |
+| --- | --- | --- |
+| <a href="https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-room-state/index.html">RoomStatus</a> | <code>enum class</code> | Current status of the room:<br>- <code>SCHEDULED</code> (scheduled).<br>- <code>RUNNING</code> (in progress). |
+| <a href="https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-schedule-room-options/index.html">ScheduleRoomOptions</a> | <code>data class</code> | The data structure for scheduled rooms, including start time, end time, participant list, and more. |
+| <a href="https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-room-state/index.html">RoomState</a> | <code>data class</code> | Core data structure for room state management. Maintains user-related room state information.<br>Key properties:<br>- <code>scheduledRoomList</code>: List of all scheduled rooms under the current account.<br>- <code>scheduledRoomListCursor</code>: Pagination cursor for the scheduled room list. |
+| <a href="https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-room-listener/index.html">RoomListener</a> | <code>abstract class</code> | Handles real-time events related to room activity, including scheduled room events. |
+| <a href="https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-room-store/index.html">RoomStore</a> | <code>abstract class</code> | The class for managing the entire room lifecycle. Use it to schedule rooms, retrieve scheduled room lists, and subscribe to <code>RoomListener</code> 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:**
+
+   ``` java
+   import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+   import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+   import io.trtc.tuikit.atomicxcore.api.room.ScheduleRoomOptions
+
+   // Schedule a room
+   fun scheduleRoom() {
+       val startTime = (System.currentTimeMillis() / 1000) + 60 * 15 // Start time: now + 15 minutes
+       val endTime = startTime + 60 * 30 // End time: start time + 30 minutes
+       val reminderSeconds = 60 * 5 // Reminder: 5 minutes before start
+
+       // Create room options
+       val options = ScheduleRoomOptions(
+           roomName = "Room Name",
+           scheduleStartTime = startTime,
+           scheduleEndTime = endTime,
+           reminderSecondsBeforeStart = reminderSeconds,
+           scheduleAttendees = listOf("user01", "user02", "user03"), // Participant user IDs
+           password = "Room Password", // Optional, empty string for no password
+           isAllMicrophoneDisabled = false, // Default: allow microphones
+           isAllCameraDisabled = false, // Default: allow cameras
+           isAllScreenShareDisabled = false, // Default: allow screen sharing
+           isAllMessageDisabled = 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 Parameters**
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| <code>roomID</code> | <code>String</code> | Yes | - Unique string identifier for the room.<br>- Length: 0–48 bytes.<br>- Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
+| <code>options</code> | <code>ScheduleRoomOptions</code> | Yes | Room configuration object. See ScheduleRoomOptions Struct Details. |
+| <code>completion</code> | <code>CompletionHandler</code> | No | Callback for operation completion. Returns result or error code/message if scheduling fails. |
+
+`ScheduleRoomOptions`** Struct Details**
+
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| <code>roomName</code> | <code>String</code> | No | - Room name (optional, defaults to "").<br>- Length: 0–60 bytes.<br>- Supports Chinese, English, numbers, and special characters. |
+| <code>password</code> | <code>String</code> | No | - Room password ("" means no password).<br>- Length: 0–32 bytes.<br>- 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. |
+| <code>scheduleStartTime</code> | <code>Long</code> | Yes | - Scheduled start time (Unix timestamp in seconds).<br>- Must be greater than the current time.<br>- We recommend aligning to a future minute. Example: 1736164800 (2025-01-06 20:00:00). |
+| <code>scheduleEndTime</code> | <code>Long</code> | Yes | Scheduled end time (Unix timestamp in seconds).<br>- Must be greater than <code>scheduleStartTime</code>.<br>- Set based on expected duration, e.g., <code>scheduleStartTime</code> + 3600 for one hour. |
+| <code>reminderSecondsBeforeStart</code> | <code>Int</code> | No | - Reminder time before the scheduled start (seconds). Used for system-triggered notifications.<br>- Recommended: 300 (5 min) or 900 (15 min) for local app notifications. |
+| <code>scheduleAttendees</code> | <code>List</code> | No | - List of participant user IDs. The system will send invitations to these users.<br>- For details, see retrieving the participant list for scheduled rooms. |
+| <code>isAllMicrophoneDisabled</code> | <code>Boolean</code> | No | Whether to mute all participants by default.<br>- true: Disabled.<br>- false: Not disabled (default). |
+| <code>isAllCameraDisabled</code> | <code>Boolean</code> | No | Whether to disable all participant cameras by default.<br>- true: Disabled.<br>- false: Not disabled (default). |
+| <code>isAllScreenShareDisabled</code> | <code>Boolean</code> | No | Whether to disable screen sharing for all participants.<br>- true: Disabled.<br>- false: Not disabled (default). |
+| <code>isAllMessageDisabled</code> | <code>Boolean</code> | No | Whether to mute chat messages for all participants.<br>- true: Disabled.<br>- false: Not disabled (default). |
+
+#### 2. Cancel a Scheduled Room
+
+The room scheduler can call `RoomStore.cancelScheduledRoom` to cancel a scheduled room.
+``` java
+import android.util.Log
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+
+// Cancel a scheduled room
+fun 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.
+``` java
+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.ScheduleRoomOptions
+
+// Update a scheduled room
+fun updateScheduledRoom() {
+    val newStartTime = (System.currentTimeMillis() / 1000) + 60 * 30 // Start: now + 30 minutes
+    val newEndTime = newStartTime + 60 * 45 // End: start + 45 minutes
+
+    val 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`** Parameters**
+| Parameter | Type | Required | Description |
+| --- | --- | --- | --- |
+| <code>roomID</code> | <code>String</code> | Yes | - Unique string identifier for the room.<br>- Length: 0–48 bytes.<br>- Use only numbers, English letters (case sensitive), underscores (_), and hyphens (-). Avoid spaces and Chinese characters. |
+| <code>options</code> | <code>ScheduleRoomOptions</code> | Yes | Configuration object for the scheduled room.<br>- See details in ScheduleRoomOptions struct. |
+| <code>modifyFlagList</code> | <code>List<ScheduleRoomOptions.ModifyFlag></code> | Yes | Flags specifying which room properties to update. Can update room name, start time, and end time. See <code>ModifyFlag</code> documentation. |
+| <code>completion</code> | <code>CompletionHandler</code> | No | Callback for completion. Returns result or error code/message if update fails. |
+
+`ScheduleRoomOptions.ModifyFlag`** Details**
+| Parameter | Type | Description |
+| --- | --- | --- |
+| <code>ROOM_NAME</code> | <code>enum</code> | - Use this flag when updating the scheduled room name.<br>- You must also set the <code>roomName</code> field in <code>ScheduleRoomOptions</code>. |
+| <code>SCHEDULE_START_TIME</code> | <code>enum</code> | - Use this flag when updating the scheduled room start time.<br>- You must also set the <code>scheduleStartTime</code> field in <code>ScheduleRoomOptions</code>. |
+| <code>SCHEDULE_END_TIME</code> | <code>enum</code> | - Use this flag when updating the scheduled room end time.<br>- You must also set the <code>scheduleEndTime</code> field in <code>ScheduleRoomOptions</code>. |
+
+#### 4. Add or Remove Participants
+
+To add or remove participants in a scheduled room, use `RoomStore.addScheduledAttendees` or `RoomStore.removeScheduledAttendees`.
+``` java
+import android.util.Log
+import io.trtc.tuikit.atomicxcore.api.CompletionHandler
+import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+
+// Add scheduled participants
+fun 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 participants
+fun 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.
+``` java
+import android.util.Log
+import io.trtc.tuikit.atomicxcore.api.ListResultCompletionHandler
+import io.trtc.tuikit.atomicxcore.api.room.RoomInfo
+import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+
+// Get scheduled room list
+fun getScheduledRoomList(cursor: String? = null) {
+    // Use null for the first page; use the previous nextCursor for subsequent pages
+    RoomStore.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.
+``` java
+import android.util.Log
+import io.trtc.tuikit.atomicxcore.api.ListResultCompletionHandler
+import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+import io.trtc.tuikit.atomicxcore.api.room.RoomUser
+
+// Get participant list for a scheduled room
+fun getScheduledAttendees(roomID: String, cursor: String? = null) {
+    // Use null for the first page; use the previous nextCursor for subsequent pages
+    RoomStore.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:
+``` java
+import android.util.Log
+import io.trtc.tuikit.atomicxcore.api.room.RoomInfo
+import io.trtc.tuikit.atomicxcore.api.room.RoomListener
+import io.trtc.tuikit.atomicxcore.api.room.RoomStore
+import 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:
+``` java
+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 scheduled room list state changes
+private 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.).|[API Documentation](https://tencent-rtc.github.io/TUIKit_Android/-atomic-x%20-core%20-a-p-i/io.trtc.tuikit.atomicxcore.api.room/-room-store/index.html)|
+
+## 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.

package/resource/knowledge/roomkit/core-sdk/flutter/call-user-to-room.md

@@ -0,0 +1,230 @@
+`RoomStore` 是 `AtomicXCore` 中专职房间事务管理的模块，深度集成了会中呼叫能力。本章节旨在指导如何利用 `RoomStore` 高效完成会中呼叫相关功能的开发与接入。
+
+## 核心功能
+- **会中呼叫**：房间内任意参与者均可呼叫房间外任意成员加入房间。
+
+- **获取会中呼叫用户列表**：可以获取指定房间的会中呼叫的用户列表。
+
+## 核心概念
+
+在开始集成之前，需要通过下表了解一下 `RoomStore` 中与会中呼叫相关的几个核心概念：
+| <strong>核心概念</strong> | <strong>核心职责与描述</strong> |
+| --- | --- |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomCallStatus.html">RoomCallStatus</a> | 代表会中呼叫的状态，包含：<br>- <code>none</code>（默认态）。<br>- <code>calling</code>（呼叫中）。<br>- <code>timeout</code>（呼叫超时）。<br>- <code>rejected</code>（呼叫被拒绝）。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomCallResult.html">RoomCallResult</a> | 代表会中呼叫的结果，包含：<br>- <code>success</code>（呼叫成功）。<br>- <code>alreadyInCalling</code>（已在呼叫中）。<br>- <code>alreadyInRoom</code>（已在房间中）。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/CallRejectionReason.html">CallRejectionReason</a> | 代表呼叫被拒绝的原因，目前仅支持：<br>- <code>rejected</code>（主动拒绝）。<br>- <code>inOtherRoom</code>（在其他房间中）。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomCall-class.html">RoomCall</a> | 代表会中呼叫业务的核心数据结构。负责存储呼叫者信息、被呼叫者信息、以及当前呼叫状态。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener-class.html">RoomListener</a> | 代表房间动态的实时事件。其中包含会中呼叫相关的事件。 |
+| <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomStore-class.html">RoomStore</a> | 这是与房间全生命周期相关的核心类。功能包含：发起会中呼叫，响应会中呼叫，获取房间的会中呼叫列表，并通过订阅其 <code>RoomListener</code> 来接收与会中呼叫相关的实时动态事件。 |
+
+## 实现步骤
+
+### 步骤1：组件集成
+
+请参考 接入概览 集成 **AtomicXCore SDK**，并已完成 实现登录逻辑 部分接入。
+
+### 步骤2：呼叫方功能
+
+#### **1. 发起呼叫**
+
+作为呼叫方调用 `RoomStore` 的 `callUserToRoom` 接口，可以批量呼叫用户进房。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+Future<void> callUserToRoom({
+  required List<String> userIDList,
+  int timeout = 30,
+  String? extensionInfo,
+}) async {
+  final result = await RoomStore.shared.callUserToRoom(
+    roomID: "roomID",
+    userIDList: userIDList,
+    timeout: timeout,
+    extensionInfo: extensionInfo,
+  );
+
+  if (result.isSuccess) {
+    print("呼叫用户请求发送成功");
+  } else {
+    print("呼叫用户失败: [错误码: ${result.errorCode}]: ${result.errorMessage}");
+  }
+}
+```
+
+#### **2. 取消呼叫**
+
+作为呼叫方调用 `RoomStore` 的 `cancelCall` 接口，可以批量取消正在呼叫的申请。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+Future<void> cancelCall(List<String> userIDList) async {
+  final result = await RoomStore.shared.cancelCall(
+    roomID: "roomID",
+    userIDList: userIDList,
+  );
+
+  if (result.isSuccess) {
+    print("取消呼叫成功");
+  } else {
+    print("取消呼叫失败: [错误码: ${result.errorCode}]: ${result.errorMessage}");
+  }
+}
+```
+
+#### **3. 获取呼叫列表信息**
+
+进入房间后，调用 `RoomStore` 的 `getPendingCalls` 接口，可以分页查询当前房间正在呼叫的用户列表信息。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+Future<void> getPendingCalls(String roomID, String? cursor) async {
+  // cursor 为分页游标，首次调用时传入 null，获取第一页数据，后续调用时传入上次返回的 cursor 值。
+  final result = await RoomStore.shared.getPendingCalls(
+    roomID: roomID,
+    cursor: cursor,
+  );
+
+  if (result.isSuccess) {
+    print("获取呼叫列表成功，列表信息: ${result.data}, 分页游标: ${result.cursor}");
+  } else {
+    print("获取呼叫列表失败: [错误码: ${result.errorCode}]: ${result.errorMessage}");
+  }
+}
+```
+
+#### **4. 订阅会中呼叫事件**
+
+作为呼叫方订阅 `RoomStore` 的 `RoomListener` 能够实时获取呼叫的生命周期事件。通过监听以下回调，可以精准捕捉呼叫的最终结果并据此更新 UI 状态或执行后续业务逻辑。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+late RoomListener _listener;
+
+/// 订阅会中呼叫相关事件
+void addRoomCallListener() {
+  _listener = RoomListener(
+    onCallTimeout: (roomInfo, call) {
+      print("呼叫超时 房间信息: ${roomInfo.roomID}, 呼叫者: ${call.caller.userID}");
+    },
+    onCallAccepted: (roomInfo, call) {
+      print("呼叫已被接受 房间信息: ${roomInfo.roomID}, 被呼叫者: ${call.callee.userID}");
+    },
+    onCallRejected: (roomInfo, call, reason) {
+      print("呼叫被拒绝 房间信息: ${roomInfo.roomID}, 被呼叫者: ${call.callee.userID}, 拒绝原因: $reason");
+    },
+  );
+
+  RoomStore.shared.addRoomListener(_listener);
+}
+
+void removeRoomCallListener() {
+  RoomStore.shared.removeRoomListener(_listener);
+}
+```
+
+**呼叫事件函数详细说明**
+
+|事件函数|触发时机与说明|
+|---------|---------|
+|[onCallTimeout](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallTimeout.html)|呼叫超时。当呼叫请求在预设的时间内（由调用 callUserToRoom 时指定）未得到被呼叫方的响应时触发。此时，呼叫自动结束，呼叫方通常需要提示“对方无人接听”。|
+|[onCallAccepted](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallAccepted.html)|呼叫被接受。被呼叫方主动点击了“接听”或“接受”按钮。收到此回调后，表示被呼叫者即将进入房间，呼叫方应更新 UI 状态，例如将该用户从“呼叫中”列表移除，并等待后续的成员进房通知来刷新成员列表。|
+|[onCallRejected](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallRejected.html)|呼叫被拒绝。被呼叫方主动拒绝了通话请求，或者因为被呼叫方当前正处于其他房间中而自动拒绝。回调中通常包含拒绝原因（如主动拒绝或在其他房间中）。|
+
+### 步骤3：被呼叫方功能
+
+#### **1. 订阅会中呼叫事件**
+
+作为被呼叫方订阅 `RoomStore` 的 `RoomListener` 可以实时监听并响应来自呼叫方的呼叫行为。以下是构建呼叫提醒界面以及维护呼叫链路状态的关键事件。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+late RoomListener _listener;
+
+/// 订阅会中呼叫相关事件
+void addRoomCallListener() {
+  _listener = RoomListener(
+    onCallReceived: (roomInfo, call, extensionInfo) {
+      print("收到房间呼叫 房间信息: ${roomInfo.roomID}, 呼叫者: ${call.caller.userID}, 扩展信息: $extensionInfo");
+    },
+    onCallCancelled: (roomInfo, call) {
+      print("呼叫被取消 房间信息: ${roomInfo.roomID}, 呼叫者: ${call.caller.userID}");
+    },
+    onCallRevokedByAdmin: (roomInfo, call, operatorUser) {
+      print("呼叫被管理员移除 房间信息: ${roomInfo.roomID}, 呼叫者: ${call.caller.userID}, 移除操作者: ${operatorUser.userID}");
+    },
+    onCallHandledByOtherDevice: (roomInfo, isAccepted) {
+      print("呼叫已被其他设备处理 房间信息: ${roomInfo.roomID}, 处理结果: $isAccepted");
+    },
+  );
+
+  RoomStore.shared.addRoomListener(_listener);
+}
+
+void removeRoomCallListener() {
+  RoomStore.shared.removeRoomListener(_listener);
+}
+```
+
+**事件函数详细说明**
+
+|事件函数|触发时机与说明|
+|---------|---------|
+|[onCallReceived](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallReceived.html)|收到呼叫邀请。当有其他用户向您发起入会邀请时触发。收到此回调后，被呼叫方通常应立即弹出“呼叫提醒”界面，展示呼叫者信息、房间信息，并提供“接听”和“拒绝”按钮。|
+|[onCallCancelled](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallCancelled.html)|呼叫被发起方取消。呼叫方在您未做出响应前，主动撤回了呼叫请求。收到此回调后，被呼叫方应立即关闭当前的来电界面，并提示“对方已取消呼叫”，以恢复应用正常操作流程。|
+|[onCallRevokedByAdmin](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallRevokedByAdmin.html)|呼叫被管理员撤销。房间管理员或后台系统因权限变更、房间解散等原因强行终止了该笔呼叫邀请。收到此通知后，被呼叫方需立即停止呼叫流程并隐藏相关 UI，处理逻辑通常类似于呼叫被取消。|
+|[onCallHandledByOtherDevice](https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomListener/onCallHandledByOtherDevice.html)|呼叫已在其他设备处理。当用户在多个设备（例如手机和 iPad）同时登录时，如果呼叫已在其中一台设备上被处理（接受或拒绝），当前设备会收到此通知，用于同步 UI 状态并自动消除呼叫界面。|
+
+#### **2. 接受呼叫、拒绝呼叫**
+
+作为被呼叫方调用 `RoomStore` 的 `acceptCall` 或者 `rejectCall` 接口，处理接受或者拒绝呼叫邀请。
+``` java
+import 'package:atomic_x_core/atomicxcore.dart';
+
+late RoomListener _listener;
+
+/// 订阅会中呼叫相关事件
+void addRoomCallListener() {
+  _listener = RoomListener(
+    onCallReceived: (roomInfo, call, extensionInfo) {
+      print("收到房间呼叫 房间信息: ${roomInfo.roomID}, 呼叫者: ${call.caller.userID}, 扩展信息: $extensionInfo");
+      // 接受、拒绝呼叫邀请操作
+    },
+  );
+
+  RoomStore.shared.addRoomListener(_listener);
+}
+
+void removeRoomCallListener() {
+  RoomStore.shared.removeRoomListener(_listener);
+}
+
+// 接受呼叫邀请
+Future<void> acceptCall(String roomID) async {
+  final result = await RoomStore.shared.acceptCall(roomID);
+
+  if (result.isSuccess) {
+    print("接受呼叫成功，房间ID: $roomID");
+  } else {
+    print("接受呼叫失败: [错误码: ${result.errorCode}] ${result.errorMessage}");
+  }
+}
+
+// 拒绝呼叫邀请
+Future<void> rejectCall(String roomID, {CallRejectionReason reason = CallRejectionReason.rejected}) async {
+  final result = await RoomStore.shared.rejectCall(
+    roomID: roomID,
+    reason: reason,
+  );
+
+  if (result.isSuccess) {
+    print("拒绝呼叫成功，房间ID: $roomID");
+  } else {
+    print("拒绝呼叫失败: [错误码: ${result.errorCode}] ${result.errorMessage}");
+  }
+}
+```
+
+## API 文档
+| <strong>Store/Component</strong> | <strong>功能描述</strong> | <strong>API 文档</strong> |
+| --- | --- | --- |
+| <strong>RoomStore</strong> | 房间全生命周期管理：创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 预定房间 / 呼叫房间外成员 / 监听房间内被动事件（例如房间解散，房间信息更新等）。 | <a href="https://tencent-rtc.github.io/TUIKit_Flutter/api_room_room_store/RoomStore-class.html">API 文档</a> |