using Dpz.Core.Web.Jobs.Models.FileTransfer;

namespace Dpz.Core.Web.Jobs.Services.FileTransfer;

/// <summary>
/// 文件传输会话服务。
/// </summary>
public interface IFileTransferSessionService
{
    /// <summary>接收方加入房间。</summary>
    FileTransferOperationResult<FileTransferRoomResult> JoinRoom(
        string roomKey,
        string connectionId,
        string joinUrl
    );

    /// <summary>发送方发起一个文件传输要约。</summary>
    FileTransferOperationResult<FileTransferRecord> AddTransferOffer(
        string roomKey,
        string connectionId,
        FileTransferMetadata metadata
    );

    /// <summary>接收方接受传输要约。</summary>
    FileTransferOperationResult<FileTransferRecord> AcceptTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>接收方拒绝传输要约。</summary>
    FileTransferOperationResult<FileTransferRecord> RejectTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>暂停指定文件的传输。</summary>
    FileTransferOperationResult<FileTransferRecord> PauseTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>恢复暂停的文件传输。</summary>
    FileTransferOperationResult<FileTransferRecord> ResumeTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>取消指定文件的传输。</summary>
    FileTransferOperationResult<FileTransferRecord> CancelFileTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>发送方发送一个文件分片。</summary>
    FileTransferOperationResult<FileTransferRoom> SendChunk(
        string roomKey,
        string connectionId,
        FileTransferChunk chunk
    );

    /// <summary>接收方确认分片（空调用，仅校验房间和权限）。</summary>
    FileTransferOperationResult<FileTransferRoom> AcknowledgeChunk(
        string roomKey,
        string connectionId
    );

    /// <summary>发送方通知传输完成。</summary>
    FileTransferOperationResult<FileTransferRecord> CompleteTransfer(
        string roomKey,
        string connectionId,
        string transferId
    );

    /// <summary>关闭房间，仅房间参与者可调用。</summary>
    FileTransferOperationResult<FileTransferRoom> CloseRoom(string roomKey, string connectionId);
}