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

package/resource/knowledge/livekit/core-sdk/api-reference/ios/BattleStore.md

@@ -0,0 +1,309 @@
+## 简介
+
+PK 功能实现主播之间的实时互动对战。`BattleStore` 提供了一套全面的 API 来管理整个 PK 生命周期。
+
+> **重要：**
+>
+
+> 请始终使用工厂方法 **create(liveID:)** 并提供有效的直播间 ID 来创建 `BattleStore` 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> PK 状态更新通过 **state** 发布者传递。订阅它以接收有关 PK 信息、参与用户和分数的实时更新。
+>
+
+> **警告：**
+>
+
+> 如果 PK 请求在指定的超时时间内未收到响应，将触发超时事件。请始终在 UI 中处理超时场景。
+>
+
+## 功能特性
+- **PK 请求管理**：主播可以发起 PK 请求，被邀请方可以接受或拒绝。
+
+- **状态管理**：实时跟踪 PK 信息、参与用户和分数。
+
+- **事件驱动架构**：提供完整的 PK 事件回调。
+
+- **超时处理**：为 PK 请求提供内置超时机制。
+
+## 可订阅数据
+
+**BattleState** 的字段描述如下：
+
+|**属性名**|**类型**|**描述**|
+|---------|---------|---------|
+|currentBattleInfo|BattleInfo?|当前 PK 信息。|
+|battleUsers|[SeatUserInfo]|PK 用户列表。|
+|battleScore|[String:UInt]|PK 分数的映射。|
+
+## API 列表
+
+|**函数名**|**描述**|
+|---------|---------|
+|create|创建 BattleStore 实例。|
+|battleEventPublisher|新增 PK 事件回调。|
+|requestBattle|发起 PK 请求。|
+|cancelBattleRequest|取消 PK 请求。|
+|acceptBattle|接受 PK 请求。|
+|rejectBattle|拒绝 PK 请求。|
+|exitBattle|退出 PK。|
+
+### 创建实例
+
+#### create
+
+创建 BattleStore 实例。
+``` swift
+public static func create(liveID: String) -> BattleStore {
+    let store: BattleStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
+    return store
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|liveID|String|直播间 ID。|
+
+### 观察状态和事件
+
+#### battleEventPublisher
+
+新增 PK 事件回调。
+
+PK 事件发布者。
+
+**数据结构：**BattleEvent
+
+### PK 操作
+
+#### requestBattle
+
+发起 PK 请求。
+``` swift
+public func requestBattle(config: BattleConfig, userIDList: [String], timeout: TimeInterval, completion: BattleRequestClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|config|BattleConfig|PK 配置。|
+|userIDList|[String]|希望邀请 PK 的其他主播用户 ID 列表。请传入您想要 PK 的对方主播用户 ID，请注意不要在此列表中包含当前用户自己的 ID。|
+|timeout|TimeInterval|超时时间（单位：秒），最大限制为30秒。|
+|completion|BattleRequestClosure?|发起请求成功的回调。|
+
+#### cancelBattleRequest
+
+取消 PK 请求。
+``` swift
+public func cancelBattleRequest(battleId: String, userIdList: [String], completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleId|String|PK ID。|
+|userIdList|[String]|用户 ID 列表。|
+|completion|CompletionClosure?|取消请求成功的回调。|
+
+#### acceptBattle
+
+接受 PK 请求。
+``` swift
+public func acceptBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|completion|CompletionClosure?|接受成功的回调。|
+
+#### rejectBattle
+
+拒绝 PK 请求。
+``` swift
+public func rejectBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|completion|CompletionClosure?|拒绝成功的回调。|
+
+#### exitBattle
+
+退出 PK。
+``` swift
+public func exitBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|completion|CompletionClosure?|退出 PK 成功的回调。|
+
+## 数据结构
+
+### BattleEndedReason
+
+正在 PK 中用户收到 PK 结束的原因。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|timeOver|0|PK 倒计时结束。|
+|allMemberExit|1|所有 PK 成员退出。|
+
+### BattleEvent
+
+收到 PK 相关的回调事件。
+
+|**枚举值**|**说明**|
+|---------|---------|
+|onBattleStarted|当 PK 正式开始时触发此回调，通知所有参与者 PK 已经开始。|
+|onBattleEnded|当 PK 结束时触发此回调。|
+|onUserJoinBattle|当有用户加入 PK 时触发此回调。|
+|onUserExitBattle|当有用户退出 PK 时触发此回调。|
+|onBattleRequestReceived|当收到 PK 请求时触发此回调。|
+|onBattleRequestCancelled|当 PK 请求被取消时触发此回调。|
+|onBattleRequestTimeout|当 PK 请求超时时触发此回调。|
+|onBattleRequestAccept|当 PK 请求被接受时触发此回调。|
+|onBattleRequestReject|当 PK 请求被拒绝时触发此回调。|
+
+### BattleConfig
+
+发送 PK 请求时，设置的 PK 配置信息。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|duration|TimeInterval|PK 持续时间（单位：秒）。|
+|needResponse|Bool|被邀请用户是否需要回复同意/拒绝。|
+|extensionInfo|String|扩展信息。|
+
+### BattleInfo
+
+PK 信息。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|battleID|String|PK ID。|
+|config|BattleConfig|发送 PK 请求时，设置的 PK 配置信息。|
+|startTime|UInt|PK 开始标记时间戳（单位：秒）。|
+|endTime|UInt|PK 结束标记时间戳（单位：秒）。|
+
+### BattleState
+
+BattleStore 对外提供的 PK 相关状态数据。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|currentBattleInfo|BattleInfo?|当前 PK 信息。|
+|battleUsers|[SeatUserInfo]|PK 用户列表。|
+|battleScore|[String:UInt]|PK 分数的映射。|
+
+### BattleRequestCallback
+
+PK 请求回调。
+
+PK 请求的回调接口，用于处理 PK 请求的成功或失败结果。
+
+**方法**
+
+**onSuccess**: 成功回调。
+``` swift
+fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>)
+```
+
+|**参数名**|**类型**|**说明**|
+|---------|---------|---------|
+|battleInfo|BattleInfo|PK 信息，包含 PK 的详细配置和状态。|
+|resultMap|Map<String,Int>|PK 请求的响应结果回调。|
+
+**onError**: 失败回调。
+``` swift
+fun onError(code: Int, desc: String)
+```
+
+|**参数名**|**类型**|**说明**|
+|---------|---------|---------|
+|code|Int|错误码。|
+|desc|String|错误描述。|
+
+## 使用示例
+``` swift
+// 创建 store 实例
+let store = BattleStore.create(liveID: "live_room_123")
+// 订阅状态变化
+store.state.subscribe { state in
+    if let battleInfo = state.currentBattleInfo {
+        print("当前 PK ID: \(battleInfo.battleID)")
+    }
+    print("PK 用户数: \(state.battleUsers.count)")
+}
+// 订阅 PK 事件
+store.battleEventPublisher.sink { event in
+    switch event {
+    case .onBattleStarted(let battleInfo, let inviter, let invitees):
+        print("PK 开始，发起者: \(inviter.userName)")
+    case .onBattleEnded(let battleInfo, let reason):
+        print("PK 结束，原因: \(reason)")
+    default:
+        break
+    }
+}
+// 发起 PK 请求
+let config = BattleConfig(duration: 300, needResponse: true)
+store.requestBattle(config: config, userIDList: ["user_456"], timeout: 30) { result in
+    switch result {
+    case .success(let (battleInfo, resultMap)):
+        print("PK 请求成功: \(battleInfo.battleID)")
+    case .failure(let error):
+        print("PK 请求失败: \(error)")
+    }
+}
+```

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

@@ -0,0 +1,370 @@
+## 简介
+
+连麦功能通过基于麦位的系统实现主播和观众成员之间的实时互动。`CoGuestStore` 提供了一套全面的 API 来管理整个连麦生命周期。
+
+> **重要：**
+>
+
+> 请始终使用工厂方法 **create(liveID:)** 并提供有效的直播间 ID 来创建 `CoGuestStore` 实例。不要尝试直接初始化。
+>
+
+> **说明：**
+>
+
+> 连麦状态更新通过 **state** 发布者传递。订阅它以接收有关已连接用户、邀请和申请的实时更新。
+>
+
+> **警告：**
+>
+
+> 如果连麦请求在指定的超时时间内未收到响应，将触发带有 `NoResponseReason.timeout` 的事件。请始终在 UI 中处理超时场景。
+>
+
+## 功能特性
+- **双向邀请**：主播可以邀请观众成员，观众成员也可以申请加入。
+
+- **状态管理**：实时跟踪已连接用户、邀请和申请。
+
+- **事件驱动架构**：为主播和观众角色提供独立的事件流。
+
+- **超时处理**：为邀请和申请提供内置超时机制。
+
+## 可订阅数据
+
+**CoGuestState** 的字段描述如下：
+
+|**属性名**|**类型**|**描述**|
+|---------|---------|---------|
+|connected|[SeatUserInfo]|已经在麦位上的用户列表。|
+|invitees|[LiveUserInfo]|主播发出邀请的用户列表。|
+|applicants|[LiveUserInfo]|主播收到申请连麦的用户列表。|
+|candidates|[LiveUserInfo]|候选连麦的用户列表。|
+
+## API 列表
+
+|**函数名**|**描述**|
+|---------|---------|
+|create|创建对象实例。|
+|hostEventPublisher|主播端事件发布者。|
+|guestEventPublisher|观众端事件发布者。|
+|applyForSeat|观众申请连麦。|
+|cancelApplication|观众取消申请。|
+|acceptApplication|主播接受申请。|
+|rejectApplication|主播拒绝申请。|
+|inviteToSeat|主播邀请观众连麦。|
+|cancelInvitation|主播取消邀请。|
+|acceptInvitation|观众接受邀请。|
+|rejectInvitation|观众拒绝邀请。|
+|disConnect|结束连麦会话。|
+
+### 创建实例
+
+#### create
+
+创建 CoGuestStore 实例。
+``` swift
+public static func create(liveID: String) -> CoGuestStore {
+    let store: CoGuestStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
+    return store
+}
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|liveID|String|直播间 ID。|
+
+### 观察状态和事件
+
+#### hostEventPublisher
+
+主播端事件发布者。
+
+主播事件发布者。
+
+**数据结构：**HostEvent
+
+#### guestEventPublisher
+
+观众端事件发布者。
+
+观众事件发布者。
+
+**数据结构：**GuestEvent
+
+### 观众操作
+
+#### applyForSeat
+
+申请上麦。
+``` swift
+public func applyForSeat(seatIndex: Int = -1, timeout: TimeInterval, extraInfo: String?, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+以观众身份请求加入连麦会话。
+
+调用此方法后，会向直播间内的所有主播发送连麦请求。请求将保持活动状态，直到：
+• 主播通过 **acceptApplication** 接受
+• 主播通过 **rejectApplication** 拒绝
+• 超时时间到期
+• 您通过 **cancelApplication** 取消。
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 如果在超时时间内没有主播响应，将触发带有 **NoResponseReason/timeout** 的 {ref2} 事件。
+>
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|seatIndex|Int|麦位索引，-1表示自动分配麦位。|
+|timeout|TimeInterval|超时时间（单位：秒），取值范围为5到1800秒。|
+|extraInfo|String?|额外信息。|
+|completion|CompletionClosure?|完成回调。|
+
+#### cancelApplication
+
+取消上麦申请。
+``` swift
+public func cancelApplication(completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+取消之前发送的连麦申请。调用此方法后，所有主播将收到申请取消的通知。
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**注意事项**
+
+> **说明：**
+>
+
+> 如果申请已被主播处理，取消操作可能无效。
+>
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|completion|CompletionClosure?|完成回调。|
+
+#### acceptApplication
+
+接受上麦申请。
+``` swift
+public func acceptApplication(userID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|userID|String|用户 ID。|
+|completion|CompletionClosure?|完成回调。|
+
+#### rejectApplication
+
+拒绝上麦申请。
+``` swift
+public func rejectApplication(userID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|userID|String|用户 ID。|
+|completion|CompletionClosure?|完成回调。|
+
+### 主播操作
+
+#### inviteToSeat
+
+邀请观众上麦。
+``` swift
+public func inviteToSeat(userID: String, seatIndex: Int = -1, timeout: TimeInterval, extraInfo: String?, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|userID|String|被邀请用户 ID。|
+|seatIndex|Int|麦位索引，-1表示自动分配麦位。|
+|timeout|TimeInterval|超时时间（单位：秒），取值范围为5到1800秒。|
+|extraInfo|String?|额外信息。|
+|completion|CompletionClosure?|完成回调。|
+
+#### cancelInvitation
+
+取消上麦邀请。
+``` swift
+public func cancelInvitation(inviteeID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviteeID|String|被邀请用户 ID。|
+|completion|CompletionClosure?|完成回调。|
+
+#### acceptInvitation
+
+接受上麦邀请。
+``` swift
+public func acceptInvitation(inviterID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviterID|String|邀请者用户 ID。|
+|completion|CompletionClosure?|完成回调。|
+
+#### rejectInvitation
+
+拒绝上麦邀请。
+``` swift
+public func rejectInvitation(inviterID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|inviterID|String|邀请者用户 ID。|
+|completion|CompletionClosure?|完成回调。|
+
+### 连接控制
+
+#### disConnect
+
+断开连麦。
+``` swift
+public func disConnect(completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**版本信息**
+
+从3.5版本开始支持。
+
+**参数说明**
+
+|**参数名**|**类型**|**描述**|
+|---------|---------|---------|
+|completion|CompletionClosure?|完成回调。|
+
+## 数据结构
+
+### NoResponseReason
+
+主播发出的连麦邀请或者观众发起连麦请求的无响应原因。
+
+|**枚举值**|**值**|**说明**|
+|---------|---------|---------|
+|timeout|0|请求超时。|
+|alreadySeated|1|用户已在麦位上。|
+
+### HostEvent
+
+主播侧收到的回调事件。
+
+|**枚举值**|**说明**|
+|---------|---------|
+|onGuestApplicationReceived|当观众申请连麦时触发此回调。|
+|onGuestApplicationCancelled|当观众取消连麦申请时触发此回调。|
+|onGuestApplicationProcessedByOtherHost|当观众的连麦申请被其他主播处理时触发此回调。|
+|onHostInvitationResponded|当主播发出的连麦邀请收到观众响应时触发此回调。|
+|onHostInvitationNoResponse|当主播发出的连麦邀请无响应时触发此回调。|
+
+### GuestEvent
+
+观众侧收到的回调事件。
+
+|**枚举值**|**说明**|
+|---------|---------|
+|onHostInvitationReceived|当收到主播的连麦邀请时触发此回调。|
+|onHostInvitationCancelled|当主播取消连麦邀请时触发此回调。|
+|onGuestApplicationResponded|当观众的连麦申请收到主播响应时触发此回调。|
+|onGuestApplicationNoResponse|当观众的连麦申请无响应时触发此回调。|
+|onKickedOffSeat|当观众被主播踢下麦位时触发此回调。|
+
+### CoGuestState
+
+CoGuestStore 对外提供的连麦相关状态数据。
+
+|**属性**|**类型**|**说明**|
+|---------|---------|---------|
+|connected|[SeatUserInfo]|已经在麦位上的用户列表。|
+|invitees|[LiveUserInfo]|主播发出邀请的用户列表。|
+|applicants|[LiveUserInfo]|主播收到申请连麦的用户列表。|
+|candidates|[LiveUserInfo]|候选连麦的用户列表。|
+
+## 使用示例
+``` swift
+// 创建 store 实例
+let store = CoGuestStore.create(liveID: "live_room_123")
+// 订阅状态变化
+store.state.subscribe { state in
+    print("已连接用户: \(state.connected.count)")
+    print("待处理申请: \(state.applicants.count)")
+}
+// 订阅主播事件（主播使用）
+store.hostEventPublisher.sink { event in
+    switch event {
+    case .onGuestApplicationReceived(let guestUser):
+        print("收到来自 \(guestUser.userName) 的申请")
+        // 显示接受/拒绝的 UI
+    case .onHostInvitationResponded(let isAccept, let guestUser):
+        print("观众 \(guestUser.userName) \(isAccept ? "接受了" : "拒绝了")")
+    default:
+        break
+    }
+}
+// 主播：接受申请
+store.acceptApplication(userID: "user_456") { code, message in
+    if code == 0 {
+        print("申请接受成功")
+    }
+}
+```