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);