@tencentcloud/sdk-mcp 1.4.7 → 1.6.0-beta.1

package/resource/knowledge/livekit/core-sdk/api-reference/flutter/CoGuestStore.md

@@ -0,0 +1,404 @@
+## 简介
+
+连麦功能通过基于麦位的系统实现主播和观众成员之间的实时互动。`CoGuestStore` 提供了一套全面的 API 来管理整个连麦生命周期。
+
+> **重要：**
+>
+
+> 请始终使用工厂方法 **CoGuestStore.create** 并提供有效的直播间 ID 来创建 `CoGuestStore` 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> 连麦状态更新通过 **coGuestState** 发布者传递。订阅它以接收有关已连接用户、邀请和申请的实时更新。
+>
+
+> **警告：**
+>
+
+> 如果连麦请求在指定的超时时间内未收到响应，将触发带有 `NoResponseReason.timeout` 的事件。请始终在 UI 中处理超时场景。
+>
+
+## 功能特性
+- **双向邀请**：主播可以邀请观众成员，观众成员也可以申请加入。
+
+- **状态管理**：实时跟踪已连接用户、邀请和申请。
+
+- **事件驱动架构**：为主播和观众角色提供独立的事件流。
+
+- **超时处理**：为邀请和申请提供内置超时机制。
+
+## 可订阅数据
+
+**CoGuestState** 的字段描述如下：
+
+|**属性名**|**类型**|**描述**|
+|---------|---------|---------|
+|connected|ValueListenable<List<SeatUserInfo>>|已经在麦位上的用户列表。|
+|invitees|ValueListenable<List<LiveUserInfo>>|主播发出邀请的用户列表。|
+|applicants|ValueListenable<List<LiveUserInfo>>|主播收到申请连麦的用户列表。|
+|candidates|ValueListenable<List<LiveUserInfo>>|候选连麦的用户列表。|
+
+## API 列表
+
+|**函数名**|**描述**|
+|---------|---------|
+|CoGuestStore.create|创建对象实例。|
+|addHostListener|主播端事件回调。|
+|removeHostListener|主播端事件回调。|
+|addGuestListener|观众端事件回调。|
+|removeGuestListener|观众端事件回调。|
+|applyForSeat|观众申请连麦。|
+|cancelApplication|观众取消申请。|
+|acceptApplication|主播接受申请。|
+|rejectApplication|主播拒绝申请。|
+|inviteToSeat|主播邀请观众连麦。|
+|cancelInvitation|主播取消邀请。|
+|acceptInvitation|观众接受邀请。|
+|rejectInvitation|观众拒绝邀请。|
+|disconnect|结束连麦会话。|
+
+### 创建实例
+
+#### CoGuestStore.create
+
+创建对象实例。
+
+### 观察状态和事件
+
+#### addHostListener
+
+添加主播侧事件回调监听器。
+``` dart
+void addHostListener(HostListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|HostListener|监听器。|
+
+#### removeHostListener
+
+移除主播侧事件回调监听器。
+``` dart
+void removeHostListener(HostListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|HostListener|监听器。|
+
+#### addGuestListener
+
+添加观众侧事件回调监听器。
+``` dart
+void addGuestListener(GuestListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|GuestListener|监听器。|
+
+#### removeGuestListener
+
+移除观众侧事件回调监听器。
+``` dart
+void removeGuestListener(GuestListener listener);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|listener|GuestListener|监听器。|
+
+### 观众操作
+
+#### applyForSeat
+
+申请上麦。
+``` dart
+Future<CompletionHandler> applyForSeat({
+    required int seatIndex,
+    required int timeout,
+    String? extraInfo,
+});
+```
+
+以观众身份请求加入连麦会话。
+
+调用此方法后，会向直播间内的所有主播发送连麦请求。请求将保持活动状态，直到：
+• 主播通过 **acceptApplication** 接受
+• 主播通过 **rejectApplication** 拒绝
+• 超时时间到期
+• 您通过 **cancelApplication** 取消。
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 如果在超时时间内没有主播响应，将触发带有 **NoResponseReason.timeout** 的 {ref2} 事件。
+>
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|seatIndex|int|麦位索引，-1表示自动分配麦位。|
+|timeout|int|超时时间（单位：秒），取值范围为5到1800秒。|
+|extraInfo|String?|额外信息。|
+
+#### cancelApplication
+
+取消上麦申请。
+``` dart
+Future<CompletionHandler> cancelApplication();
+```
+
+取消之前发送的连麦申请。调用此方法后，所有主播将收到申请取消的通知。
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 如果申请已被主播处理，取消操作可能无效。
+>
+
+#### acceptApplication
+
+接受上麦申请。
+``` dart
+Future<CompletionHandler> acceptApplication(String userID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|userID|String|用户 ID。|
+
+#### rejectApplication
+
+拒绝上麦申请。
+``` dart
+Future<CompletionHandler> rejectApplication(String userID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|userID|String|用户 ID。|
+
+### 主播操作
+
+#### inviteToSeat
+
+邀请观众上麦。
+``` dart
+Future<CompletionHandler> inviteToSeat({
+    required String inviteeID,
+    required int seatIndex,
+    required int timeout,
+    String? extraInfo,
+});
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviteeID|String|被邀请用户 ID。|
+|seatIndex|int|麦位索引，-1表示自动分配麦位。|
+|timeout|int|超时时间（单位：秒），取值范围为5到1800秒。|
+|extraInfo|String?|额外信息。|
+
+#### cancelInvitation
+
+取消上麦邀请。
+``` dart
+Future<CompletionHandler> cancelInvitation(String inviteeID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviteeID|String|被邀请用户 ID。|
+
+#### acceptInvitation
+
+接受上麦邀请。
+``` dart
+Future<CompletionHandler> acceptInvitation(String inviterID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviterID|String|邀请者用户 ID。|
+
+#### rejectInvitation
+
+拒绝上麦邀请。
+``` dart
+Future<CompletionHandler> rejectInvitation(String inviterID);
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviterID|String|邀请者用户 ID。|
+
+### 连接控制
+
+#### disconnect
+
+结束连麦会话。
+
+## 数据结构
+
+### NoResponseReason
+
+主播发出的连麦邀请或者观众发起连麦请求的无响应原因。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|timeout|0|请求超时。|
+|alreadySeated|1|用户已在麦位上。|
+
+### HostListener
+
+主播侧收到的回调事件。
+
+**方法**
+
+|**方法名**|**说明**|
+|---------|---------|
+|onGuestApplicationReceived|当观众申请连麦时触发此回调。|
+|onGuestApplicationCancelled|当观众取消连麦申请时触发此回调。|
+|onGuestApplicationProcessedByOtherHost|当观众的连麦申请被其他主播处理时触发此回调。|
+|onHostInvitationResponded|当主播发出的连麦邀请收到观众响应时触发此回调。|
+|onHostInvitationNoResponse|当主播发出的连麦邀请无响应时触发此回调。|
+
+### GuestListener
+
+观众侧收到的回调事件。
+
+**方法**
+
+|**方法名**|**说明**|
+|---------|---------|
+|onHostInvitationReceived|当收到主播的连麦邀请时触发此回调。|
+|onHostInvitationCancelled|当主播取消连麦邀请时触发此回调。|
+|onGuestApplicationResponded|当观众的连麦申请收到主播响应时触发此回调。|
+|onGuestApplicationNoResponse|当观众的连麦申请无响应时触发此回调。|
+|onKickedOffSeat|当观众被主播踢下麦位时触发此回调。|
+
+### CoGuestState
+
+CoGuestStore 对外提供的连麦相关状态数据。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|connected|ValueListenable<List<SeatUserInfo>>|已经在麦位上的用户列表。|
+|invitees|ValueListenable<List<LiveUserInfo>>|主播发出邀请的用户列表。|
+|applicants|ValueListenable<List<LiveUserInfo>>|主播收到申请连麦的用户列表。|
+|candidates|ValueListenable<List<LiveUserInfo>>|候选连麦的用户列表。|
+
+## 使用示例
+``` dart
+// 创建 store 实例
+final store = CoGuestStore.create('live_room_123');
+// 定义监听器
+late final VoidCallback connectedListener = _onConnectedChanged;
+late final VoidCallback applicantsListener = _onApplicantsChanged;
+void _onConnectedChanged() {
+    print('已连接用户: ${store.coGuestState.connected.value.length}');
+}
+void _onApplicantsChanged() {
+    print('待处理申请: ${store.coGuestState.applicants.value.length}');
+}
+// 订阅状态变化
+store.coGuestState.connected.addListener(connectedListener);
+store.coGuestState.applicants.addListener(applicantsListener);
+// 添加主播事件监听器（主播使用）
+final hostListener = HostListener(
+    onGuestApplicationReceived: (guestUser) {
+        print('收到来自 ${guestUser.userName} 的申请');
+        // 显示接受/拒绝的 UI
+    },
+    onHostInvitationResponded: (isAccept, guestUser) {
+        print('观众 ${guestUser.userName} ${isAccept ? "接受了" : "拒绝了"}');
+    },
+);
+store.addHostListener(hostListener);
+// 主播：接受申请
+final result = await store.acceptApplication('user_456');
+if (result.code == 0) {
+    print('申请接受成功');
+}
+// 完成后取消订阅
+store.coGuestState.connected.removeListener(connectedListener);
+store.coGuestState.applicants.removeListener(applicantsListener);
+store.removeHostListener(hostListener);
+```