@tencentcloud/sdk-mcp 1.3.8 → 1.4.0

package/resource/doc/livekit/core-sdk/live/android/api-reference/CoGuestStore.md

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