CoHostStore
Introduction
Cross-room connection feature allows hosts from different live rooms to interact in real-time. CoHostStore provides a comprehensive set of APIs to manage the entire cross-room connection lifecycle.
Important:
Always use the factory method CoHostStore.create with a valid live room ID to create a CoHostStore instance. Do not attempt to initialize directly.
Note:
Connection state updates are delivered through the coHostState publisher. Subscribe to it to receive real-time updates about connection status, connected hosts, invitations and applications.
Warning:
If a connection request does not receive a response within the specified timeout, the timeout event will be triggered. Always handle timeout scenarios in your UI.
Features
Bidirectional Connection：Hosts can initiate connection requests to other hosts, and also receive connection requests from other hosts
State Management：Real-time tracking of connection status, connected hosts, invitation list and applicants
Event-Driven Architecture：Provides connection event stream for monitoring various connection state changes
Layout Templates：Supports multiple connection layout templates, such as dynamic grid layout and 1-to-6 layout
Subscribable Data
CoHostState fields are described below:
Property | Type | Description |
coHostStatus | Real-time cross-room connection status. | |
connected | List of hosts currently connected with current live room. | |
invitees | List of hosts to whom requests have been sent. | |
applicant | Host who initiated connection request to current live room. | |
candidatesCursor | ValueListenable<String> | Recommended user list cursor. |
candidates | Recommended user list. |
API List
Function | Description |
Create object instance. | |
Connection event callbacks. | |
Connection event callbacks. | |
Initiate connection request. | |
Cancel connection request. | |
Accept connection request. | |
Reject connection request. | |
Exit connection. | |
Get recommended host list. |
Creating Instance
CoHostStore.create
Create object instance
Observing State and Events
addCoHostListener
Add connection callback listener
void addCoHostListener(CoHostListener listener);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
listener | Required | Listener. |
removeCoHostListener
Remove connection callback listener
void removeCoHostListener(CoHostListener listener);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
listener | Required | Listener. |
Connection Operations
requestHostConnection
Initiate host connection request
Future<CompletionHandler> requestHostConnection({required String targetHostLiveID,required CoHostLayoutTemplate layoutTemplate,required int timeout,String extraInfo = '',});
Initiate a cross-room connection request to target host.
After calling this method, a connection request is sent to the target host. The request will remain active until:
• Target host accepts via acceptHostConnection(fromHostLiveID:completion:)
• Target host rejects via rejectHostConnection(fromHostLiveID:completion:)
• Timeout expires
• You cancel via cancelHostConnection(toHostLiveID:completion:)
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
targetHostLiveID | String | Required | Target host's live room ID. |
layoutTemplate | Required | Connection layout template. | |
timeout | int | Required | Request timeout (unit: seconds). |
extraInfo | String? | Required | Extension information. |
cancelHostConnection
Cancel host connection request
Future<CompletionHandler> cancelHostConnection(String toHostLiveID);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
toHostLiveID | String | Required | Target host's live room ID. |
acceptHostConnection
Accept host connection request
Future<CompletionHandler> acceptHostConnection(String fromHostLiveID);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
fromHostLiveID | String | Required | Live room ID of the host initiating connection request. |
rejectHostConnection
Reject host connection request
Future<CompletionHandler> rejectHostConnection(String fromHostLiveID);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
fromHostLiveID | String | Required | Live room ID of the host initiating connection request. |
exitHostConnection
Exit host connection
Future<CompletionHandler> exitHostConnection();
Version
Supported since version 3.5.
getCoHostCandidates
Get recommended host list that can connect with current host
Future<CompletionHandler> getCoHostCandidates(String cursor);
Version
Supported since version 3.5.
Parameters
Parameter | Type | Required | Description |
cursor | String | Required | Cursor. |
Data Structures
CoHostStatus
Current user's cross-room connection status
Enum Value | Value | Description |
connected | 0 | Currently connected with other hosts. |
disconnected | 1 | Not connected with other hosts. |
CoHostLayoutTemplate
Connection layout template
Enum Value | Value | Description |
hostVoiceConnection | 2 | Voice chat room connection layout. |
hostDynamicGrid | 600 | Host dynamic grid layout. |
hostDynamic1v6 | 601 | Host dynamic 1v6 layout. |
CoHostListener
Connection request callback events
Methods
Method | Description |
onCoHostRequestReceived | This callback is triggered when a connection request is received. |
onCoHostRequestCancelled | This callback is triggered when a connection request is cancelled. |
onCoHostRequestAccepted | This callback is triggered when a connection request is accepted. |
onCoHostRequestRejected | This callback is triggered when a connection request is rejected. |
onCoHostRequestTimeout | This callback is triggered when a connection request times out. |
onCoHostUserJoined | This callback is triggered when a user joins the connection. |
onCoHostUserLeft | This callback is triggered when a user leaves the connection. |
CoHostState
Cross-room connection related state data provided externally by CoHostStore
Property | Type | Description |
coHostStatus | Real-time cross-room connection status. | |
connected | List of hosts currently connected with current live room. | |
invitees | List of hosts to whom requests have been sent. | |
applicant | Host who initiated connection request to current live room. | |
candidatesCursor | ValueListenable<String> | Recommended user list cursor. |
candidates | Recommended user list. |
Usage Example
// Create store instancefinal store = CoHostStore.create('live_room_123');// Define listenerslate final VoidCallback statusListener = _onStatusChanged;late final VoidCallback connectedListener = _onConnectedChanged;void _onStatusChanged() {print('Connection status: ${store.coHostState.coHostStatus.value}');}void _onConnectedChanged() {print('Connected hosts: ${store.coHostState.connected.value.length}');}// Subscribe to state changesstore.coHostState.coHostStatus.addListener(statusListener);store.coHostState.connected.addListener(connectedListener);// Add connection event listenerfinal coHostListener = CoHostListener(onCoHostRequestReceived: (inviter, extensionInfo) {print('Received connection request from ${inviter.userName}');// Show accept/reject UI},onCoHostRequestAccepted: (invitee) {print('Connection request accepted by ${invitee.userName}');},onCoHostUserJoined: (userInfo) {print('Host ${userInfo.userName} joined connection');},);store.addCoHostListener(coHostListener);// Initiate connection requestfinal result = await store.requestHostConnection(targetHostLiveID: 'target_live_id',layoutTemplate: CoHostLayoutTemplate.hostDynamicGrid,timeout: 30,extraInfo: '',);if (result.code == 0) {print('Connection request sent successfully');}// Unsubscribe when donestore.coHostState.coHostStatus.removeListener(statusListener);store.coHostState.connected.removeListener(connectedListener);store.removeCoHostListener(coHostListener);
