fcr-core/lib/utilities/join-helper.d.ts

Core APIs for building online scenes

/**
 * 房间加入辅助工具
 *
 * 提供房间控制相关的加入逻辑和参数构建，统一处理 room-control 和 room-router 中的公共逻辑
 */
import { AgoraRteScene, AgoraRteEntryRoomResponse } from '../imports';
import { FcrRoomJoinSnapshotOptions } from '../type';
import { FcrRoomJoinOptions } from '../room-control/type';
import { FcrCoreServiceApi } from '../service/api';
/**
 * 通用的加入房间重试失败处理器
 * @param error 错误对象
 * @param waitBeforeRetry 等待重试函数
 * @param attemptCount 当前重试次数
 * @param canRetryFn 判断是否可以重试的函数
 * @param onAborted 中止回调函数
 * @param logPrefix 日志前缀
 * @returns 是否继续重试
 */
export declare function handleJoinRetryFailure(error: Error, waitBeforeRetry: () => Promise<void>, attemptCount: number, canRetryFn: (error: Error) => boolean, onAborted?: () => void, logPrefix?: string): Promise<boolean>;
/**
 * 房间加入辅助工具类
 *
 * 封装了房间加入的公共逻辑，包括：
 * - 快照方式加入房间
 * - CheckIn 流程处理
 * - 重试机制
 * - 错误处理
 */
export declare class FcrJoinHelper {
    protected _userId: string;
    protected _scene: AgoraRteScene;
    protected _api: FcrCoreServiceApi;
    constructor(_userId: string, _scene: AgoraRteScene, _api: FcrCoreServiceApi);
    /**
     * 构建CheckIn请求参数（统一的参数构建方法）
     * @static
     * @param options 加入选项
     * @param userId 用户ID
     * @param roomId 房间ID
     * @param extraParams 额外参数（bypass, avatar等）
     * @returns CheckIn参数对象
     */
    static buildCheckInParams(options: FcrRoomJoinOptions, userId: string, roomId: string, extraParams?: {
        bypass?: number;
        avatar?: string;
    }): {
        avatar?: string | undefined;
        bypass?: number | undefined;
        userName: string;
        userId: string;
        userRole: "host" | "cohost" | "participant" | "audience" | "observer" | "robot";
        userProperties: Record<string, unknown> | undefined;
        roomId: string;
        platform: number;
        streams: {
            videoSourceType: import("agora-rte-sdk/lib/core/rtc/type").AgoraRtcVideoSourceType;
            audioSourceType: import("agora-rte-sdk/lib/core/rtc/type").AgoraRtcAudioSourceType;
            audioSourceState: import("agora-rte-sdk/lib/core/rtc/type").AgoraRtcMediaSourceState | undefined;
            videoSourceState: import("agora-rte-sdk/lib/core/rtc/type").AgoraRtcMediaSourceState | undefined;
            audioState: import("agora-rte-sdk/lib/core/media/type").AgoraRteMediaPublishState;
            videoState: import("agora-rte-sdk/lib/core/media/type").AgoraRteMediaPublishState;
            videoSourceUuid: string | undefined;
            audioSourceUuid: string | undefined;
            streamName: string | undefined;
        }[];
        version: string;
        password: string | undefined;
    };
    /**
     * 构建CheckIn请求参数的便捷方法（使用当前实例的配置）
     * @private
     * @param options 加入选项
     * @param extraParams 额外参数（bypass, avatar等）
     * @returns CheckIn参数对象
     */
    private _buildCheckInParams;
    /**
     *
     * @param options 加入选项
     * @param extraParams 额外参数（bypass, avatar等）
     * @param useInternalApi 是否使用 checkInInternal API（默认 true）
     * @returns CheckIn响应数据
     */
    performCheckIn(options: FcrRoomJoinOptions, extraParams?: {
        bypass?: number;
        avatar?: string;
    }, useInternalApi?: boolean): Promise<{
        data: AgoraRteEntryRoomResponse;
        ts: number;
    }>;
    /**
     * 通过 CheckIn 流程加入房间（包含重试逻辑）
     *
     * 重试逻辑说明：
     * - 重试范围：整个 "CheckIn + Join" 流程
     * - 重试原因：CheckIn 和 Join 是关联操作，如果 Join 失败需要重新 CheckIn
     * - 重试判断：使用 canRetryJoinError 判断错误是否可重试
     * - 最大重试次数：ROOM_CONTROL_CONSTANTS.MAX_JOIN_ATTEMPTS
     *
     * @param options 加入选项
     * @param onJoinAborted 加入中止检查函数
     * @returns Promise<void>
     */
    joinWithCheckIn(options: FcrRoomJoinOptions, onJoinAborted?: () => void): Promise<void>;
    /**
     * 使用快照数据加入房间的核心方法
     * @private
     */
    private _joinScene;
    /**
     * 统一的房间加入处理
     *
     * 根据选项类型自动选择合适的加入方式：
     * - 如果有 snapshot 属性：直接使用快照数据加入
     * - 否则：执行 CheckIn 流程后加入
     *
     * @param options 加入选项（支持普通加入和快照加入）
     * @param onJoinAborted 加入中止检查函数
     * @returns Promise<void>
     */
    join(options: FcrRoomJoinOptions | FcrRoomJoinSnapshotOptions, onJoinAborted?: () => void): Promise<void>;
    /**
     * 判断是否为快照加入模式
     * @private
     */
    private _isSnapshotJoin;
    /**
     * 快照加入模式：直接使用快照数据加入房间
     * @private
     */
    private _joinWithSnapshot;
}