@tencent-rtc/mcp 1.4.7 → 1.6.0

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

@@ -0,0 +1,312 @@
+## Introduction
+
+PK feature enables real-time interactive battles between hosts. `BattleStore` provides a comprehensive set of APIs to manage the entire PK lifecycle.
+
+> **Important: **
+>
+
+> Always use the factory method **create(liveID:)** with a valid live room ID to create a `BattleStore` instance. Do not attempt to initialize directly.
+>
+
+> **Note: **
+>
+
+> PK state updates are delivered through the **battleState** publisher. Subscribe to it to receive real-time updates about PK information, participating users, and scores.
+>
+
+> **Warning: **
+>
+
+> If a PK request does not receive a response within the specified timeout, a timeout event will be triggered. Always handle timeout scenarios in the UI.
+>
+
+## Features
+- **PK Request Management**: Hosts can initiate PK requests, and invitees can accept or reject.
+
+- **State Management**: Real-time tracking of PK information, participating users, and scores.
+
+- **Event-Driven Architecture**: Provides complete PK event callbacks.
+
+- **Timeout Handling**: Built-in timeout mechanism for PK requests.
+
+## Subscribable Data
+
+**BattleState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|currentBattleInfo|ValueListenable<BattleInfo?>|Current PK information.|
+|battleUsers|ValueListenable<List<SeatUserInfo>>|PK user list.|
+|battleScore|ValueListenable<Map<String,int>>|PK score mapping.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|BattleStore.create|Create BattleStore instance.|
+|addBattleListener|PK event callbacks.|
+|removeBattleListener|PK event callbacks.|
+|requestBattle|Initiate PK request.|
+|cancelBattleRequest|Cancel PK request.|
+|acceptBattle|Accept PK request.|
+|rejectBattle|Reject PK request.|
+|exitBattle|Exit PK.|
+
+### Creating Instance
+
+#### BattleStore.create
+
+Create BattleStore instance.
+
+### Observing State and Events
+
+#### addBattleListener
+
+Add PK callback listener.
+``` dart
+void addBattleListener(BattleListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|BattleListener|Listener.|
+
+#### removeBattleListener
+
+Remove PK callback listener.
+``` dart
+void removeBattleListener(BattleListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|BattleListener|Listener.|
+
+### PK Operations
+
+#### requestBattle
+
+Initiate PK request.
+``` dart
+Future<BattleRequestCompletionHandler> requestBattle({
+    required BattleConfig config,
+    required List<String> userIDList,
+    required int timeout,
+});
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|config|BattleConfig|PK configuration.|
+|userIDList|List<String>|List of user IDs to invite for PK. Please pass in the user IDs of the other hosts you wish to PK with. Note: do not include the current user's own ID in this list.|
+|timeout|int|Timeout in seconds. The maximum limit is 30 seconds.|
+
+#### cancelBattleRequest
+
+Cancel PK request.
+``` dart
+Future<CompletionHandler> cancelBattleRequest({
+    required String battleID,
+    required List<String> userIDList,
+});
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|userIDList|List<String>|User ID list.|
+
+#### acceptBattle
+
+Accept PK request.
+``` dart
+Future<CompletionHandler> acceptBattle(String battleID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+
+#### rejectBattle
+
+Reject PK request.
+``` dart
+Future<CompletionHandler> rejectBattle(String battleID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+
+#### exitBattle
+
+Exit PK.
+``` dart
+Future<CompletionHandler> exitBattle(String battleID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+
+## Data Structures
+
+### BattleEndedReason
+
+Reason for PK ending received by users in an ongoing PK.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|timeOver|0|PK countdown ended.|
+|allMemberExit|1|All PK members exited.|
+
+### BattleListener
+
+PK-related callback events received.
+
+**Methods**
+
+|**Method**|**Description**|
+|---------|---------|
+|onBattleStarted|ThiscallbackistriggeredwhenPKofficiallystarts,notifyingallparticipantsthatPKhasbegun.|
+|onBattleEnded|ThiscallbackistriggeredwhenPKends.|
+|onUserJoinBattle|ThiscallbackistriggeredwhenauserjoinsPK.|
+|onUserExitBattle|ThiscallbackistriggeredwhenauserexitsPK.|
+|onBattleRequestReceived|ThiscallbackistriggeredwhenaPKrequestisreceived.|
+|onBattleRequestCancelled|ThiscallbackistriggeredwhenaPKrequestiscancelled.|
+|onBattleRequestTimeout|ThiscallbackistriggeredwhenaPKrequesttimesout.|
+|onBattleRequestAccept|ThiscallbackistriggeredwhenaPKrequestisaccepted.|
+|onBattleRequestReject|ThiscallbackistriggeredwhenaPKrequestisrejected.|
+
+### BattleConfig
+
+PK configuration information set when sending a PK request.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|duration|int|PK duration (unit: seconds).|
+|needResponse|bool|Whether the invitee needs to reply with accept/reject.|
+|extensionInfo|String|Extension information.|
+
+### BattleInfo
+
+PK information.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|config|BattleConfig|PK configuration information set when sending a PK request.|
+|startTime|int|PK start marker timestamp (unit: seconds).|
+|endTime|int|PK end marker timestamp (unit: seconds).|
+
+### BattleState
+
+PK-related state data provided by BattleStore.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|currentBattleInfo|ValueListenable<BattleInfo?>|Current PK information.|
+|battleUsers|ValueListenable<List<SeatUserInfo>>|PK user list.|
+|battleScore|ValueListenable<Map<String,int>>|PK score mapping.|
+
+### BattleRequestCompletionHandler
+
+PK request completion handler.
+
+Completion handler for PK requests in Dart, containing the result of the PK request.
+
+**Properties**
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|battleInfo|BattleInfo?|PK information returned on success.|
+|resultMap|Map<String,int>?|Response result mapping for PK request.|
+
+## Usage Example
+``` dart
+// Create store instance
+final store = BattleStore.create('live_room_123');
+// Define listeners
+late final VoidCallback battleInfoListener = _onBattleInfoChanged;
+late final VoidCallback battleUsersListener = _onBattleUsersChanged;
+void _onBattleInfoChanged() {
+    final battleInfo = store.battleState.currentBattleInfo.value;
+    if (battleInfo != null) {
+        print('Current PK ID: ${battleInfo.battleID}');
+    }
+}
+void _onBattleUsersChanged() {
+    print('PK user count: ${store.battleState.battleUsers.value.length}');
+}
+// Subscribe to state changes
+store.battleState.currentBattleInfo.addListener(battleInfoListener);
+store.battleState.battleUsers.addListener(battleUsersListener);
+// Add PK event listener
+final battleListener = BattleListener(
+    onBattleStarted: (battleInfo, inviter, invitees) {
+        print('PK started, initiator: ${inviter.userName}');
+    },
+    onBattleEnded: (battleInfo, reason) {
+        print('PK ended, reason: $reason');
+    },
+);
+store.addBattleListener(battleListener);
+// Initiate PK request
+final config = BattleConfig(duration: 300, needResponse: true);
+final result = await store.requestBattle(
+    config: config,
+    userIDList: ['user_456'],
+    timeout: 30,
+);
+if (result.code == 0) {
+    print('PK request successful: ${result.battleInfo?.battleID}');
+} else {
+    print('PK request failed: ${result.message}');
+}
+// Unsubscribe when done
+store.battleState.currentBattleInfo.removeListener(battleInfoListener);
+store.battleState.battleUsers.removeListener(battleUsersListener);
+store.removeBattleListener(battleListener);
+```

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

@@ -0,0 +1,404 @@
+## Introduction
+
+Co-guest feature enables real-time interaction between hosts and audience members through a seat-based system. `CoGuestStore` provides a comprehensive set of APIs to manage the entire co-guest lifecycle.
+
+> **Important: **
+>
+
+> Always use the factory method **CoGuestStore.create** with a valid live room ID to create a `CoGuestStore` instance. Do not attempt to initialize directly.
+>
+
+> **Note: **
+>
+
+> Co-guest state updates are delivered through the **coGuestState** publisher. Subscribe to it to receive real-time updates about connected users, invitations and applications.
+>
+
+> **Warning: **
+>
+
+> If a co-guest request does not receive a response within the specified timeout, an event with `NoResponseReason.timeout` will be triggered. Always handle timeout scenarios in your UI.
+>
+
+## Features
+- **Bidirectional Invitation**: Hosts can invite audience members, and audience members can also apply to join.
+
+- **State Management**: Real-time tracking of connected users, invitations and applications.
+
+- **Event-Driven Architecture**: Provides separate event streams for host and guest roles.
+
+- **Timeout Handling**: Built-in timeout mechanism for invitations and applications.
+
+## Subscribable Data
+
+**CoGuestState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|connected|ValueListenable<List<SeatUserInfo>>|List of users already on seats.|
+|invitees|ValueListenable<List<LiveUserInfo>>|List of users invited by host.|
+|applicants|ValueListenable<List<LiveUserInfo>>|List of users who applied for co-guest received by host.|
+|candidates|ValueListenable<List<LiveUserInfo>>|List of candidate users for co-guest.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|CoGuestStore.create|Create object instance.|
+|addHostListener|Host-side event callbacks.|
+|removeHostListener|Host-side event callbacks.|
+|addGuestListener|Guest-side event callbacks.|
+|removeGuestListener|Guest-side event callbacks.|
+|applyForSeat|Guest applies for co-guest.|
+|cancelApplication|Guest cancels application.|
+|acceptApplication|Host accepts application.|
+|rejectApplication|Host rejects application.|
+|inviteToSeat|Host invites guest to co-guest.|
+|cancelInvitation|Host cancels invitation.|
+|acceptInvitation|Guest accepts invitation.|
+|rejectInvitation|Guest rejects invitation.|
+|disconnect|End co-guest session.|
+
+### Creating Instance
+
+#### CoGuestStore.create
+
+Create object instance.
+
+### Observing State and Events
+
+#### addHostListener
+
+Add host-side event callback listener.
+``` dart
+void addHostListener(HostListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|HostListener|Listener.|
+
+#### removeHostListener
+
+Remove host-side event callback listener.
+``` dart
+void removeHostListener(HostListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|HostListener|Listener.|
+
+#### addGuestListener
+
+Add guest-side event callback listener.
+``` dart
+void addGuestListener(GuestListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|GuestListener|Listener.|
+
+#### removeGuestListener
+
+Remove guest-side event callback listener.
+``` dart
+void removeGuestListener(GuestListener listener);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|listener|GuestListener|Listener.|
+
+### Guest Operations
+
+#### applyForSeat
+
+Apply to go on seat.
+``` dart
+Future<CompletionHandler> applyForSeat({
+    required int seatIndex,
+    required int timeout,
+    String? extraInfo,
+});
+```
+
+Request to join co-guest session as an audience member.
+
+After calling this method, a co-guest request is sent to all hosts in the live room. The request will remain active until:
+• Host accepts via **acceptApplication**
+• Host rejects via **rejectApplication**
+• Timeout expires
+• You cancel via **cancelApplication**.
+
+**Version**
+
+Supported since version 3.5.
+
+**Notes**
+
+> **Note: **
+>
+
+> If no host responds within the timeout, {ref2} event with **NoResponseReason.timeout** will be triggered.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|seatIndex|int|Seat index, -1 means auto-assign seat.|
+|timeout|int|Timeout (unit: seconds).|
+|extraInfo|String?|Extra information.|
+
+#### cancelApplication
+
+Cancel seat application.
+``` dart
+Future<CompletionHandler> cancelApplication();
+```
+
+Cancel a previously sent co-guest application. After calling this method, all hosts will be notified of the application cancellation.
+
+**Version**
+
+Supported since version 3.5.
+
+**Notes**
+
+> **Note: **
+>
+
+> If the application has already been processed by a host, the cancellation may have no effect.
+>
+
+#### acceptApplication
+
+Accept seat application.
+``` dart
+Future<CompletionHandler> acceptApplication(String userID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|User ID.|
+
+#### rejectApplication
+
+Reject seat application.
+``` dart
+Future<CompletionHandler> rejectApplication(String userID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|User ID.|
+
+### Host Operations
+
+#### inviteToSeat
+
+Invite audience to seat.
+``` dart
+Future<CompletionHandler> inviteToSeat({
+    required String inviteeID,
+    required int seatIndex,
+    required int timeout,
+    String? extraInfo,
+});
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviteeID|String|Invited user ID.|
+|seatIndex|int|Seat index, -1 means auto-assign seat.|
+|timeout|int|Timeout in seconds. Please set a value between 5 and 1800 seconds.|
+|extraInfo|String?|Extra information.|
+
+#### cancelInvitation
+
+Cancel seat invitation.
+``` dart
+Future<CompletionHandler> cancelInvitation(String inviteeID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviteeID|String|Invited user ID.|
+
+#### acceptInvitation
+
+Accept seat invitation.
+``` dart
+Future<CompletionHandler> acceptInvitation(String inviterID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviterID|String|Inviter user ID.|
+
+#### rejectInvitation
+
+Reject seat invitation.
+``` dart
+Future<CompletionHandler> rejectInvitation(String inviterID);
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviterID|String|Inviter user ID.|
+
+### Connection Control
+
+#### disconnect
+
+End co-guest session.
+
+## Data Structures
+
+### NoResponseReason
+
+Reason for no response to co-guest invitation sent by host or co-guest request initiated by audience.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|timeout|0|Request timeout.|
+|alreadySeated|1|User already on seat.|
+
+### HostListener
+
+Callback events received on host side.
+
+**Methods**
+
+|**Method**|**Description**|
+|---------|---------|
+|onGuestApplicationReceived|Thiscallbackistriggeredwhenanaudienceappliesforco-guest.|
+|onGuestApplicationCancelled|Thiscallbackistriggeredwhenanaudiencecancelsco-guestapplication.|
+|onGuestApplicationProcessedByOtherHost|Thiscallbackistriggeredwhenanaudience'sco-guestapplicationisprocessedbyanotherhost.|
+|onHostInvitationResponded|Thiscallbackistriggeredwhenaco-guestinvitationsentbyhostreceivesaresponsefromaudience.|
+|onHostInvitationNoResponse|Thiscallbackistriggeredwhenaco-guestinvitationsentbyhostreceivesnoresponse.|
+
+### GuestListener
+
+Callback events received on guest side.
+
+**Methods**
+
+|**Method**|**Description**|
+|---------|---------|
+|onHostInvitationReceived|Thiscallbackistriggeredwhenreceivingaco-guestinvitationfromhost.|
+|onHostInvitationCancelled|Thiscallbackistriggeredwhenhostcancelsco-guestinvitation.|
+|onGuestApplicationResponded|Thiscallbackistriggeredwhenaudience'sco-guestapplicationreceivesaresponsefromhost.|
+|onGuestApplicationNoResponse|Thiscallbackistriggeredwhenaudience'sco-guestapplicationreceivesnoresponse.|
+|onKickedOffSeat|Thiscallbackistriggeredwhenaudienceiskickedoffseatbyhost.|
+
+### CoGuestState
+
+Co-guest related state data provided externally by CoGuestStore.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|connected|ValueListenable<List<SeatUserInfo>>|List of users already on seats.|
+|invitees|ValueListenable<List<LiveUserInfo>>|List of users invited by host.|
+|applicants|ValueListenable<List<LiveUserInfo>>|List of users who applied for co-guest received by host.|
+|candidates|ValueListenable<List<LiveUserInfo>>|List of candidate users for co-guest.|
+
+## Usage Example
+``` dart
+// Create store instance
+final store = CoGuestStore.create('live_room_123');
+// Define listeners
+late final VoidCallback connectedListener = _onConnectedChanged;
+late final VoidCallback applicantsListener = _onApplicantsChanged;
+void _onConnectedChanged() {
+    print('Connected users: ${store.coGuestState.connected.value.length}');
+}
+void _onApplicantsChanged() {
+    print('Pending applications: ${store.coGuestState.applicants.value.length}');
+}
+// Subscribe to state changes
+store.coGuestState.connected.addListener(connectedListener);
+store.coGuestState.applicants.addListener(applicantsListener);
+// Add host event listener (for hosts)
+final hostListener = HostListener(
+    onGuestApplicationReceived: (guestUser) {
+        print('Received application from ${guestUser.userName}');
+        // Show accept/reject UI
+    },
+    onHostInvitationResponded: (isAccept, guestUser) {
+        print('Audience ${guestUser.userName} ${isAccept ? "accepted" : "rejected"}');
+    },
+);
+store.addHostListener(hostListener);
+// Host: Accept application
+final result = await store.acceptApplication('user_456');
+if (result.code == 0) {
+    print('Application accepted successfully');
+}
+// Unsubscribe when done
+store.coGuestState.connected.removeListener(connectedListener);
+store.coGuestState.applicants.removeListener(applicantsListener);
+store.removeHostListener(hostListener);
+```