ESFramework 4.0 檔案傳輸核心架構解析（上）：標準流程與基礎設施完整詳解

ESFramework 是一套高度可復用、靈活強大的 .NET 通訊框架，全採 C# 開發。內建 TCP/UDP 支援、文字/流協議、多種網路引擎，讓開發者無需處理 Socket 底層細節，專注於高層業務邏輯。適用於 IM 系統、視訊會議、資料採集等所有分散式通訊場景。

一、ESPlus 檔案傳輸標準流程

1. 發起請求：發送方呼叫 API 發起傳輸
2. 接收回應：接收方同意/拒絕，拒絕則流程結束
3. 資料傳輸：雙方自動在背景執行緒收發資料封包
4. 完成或中斷：正常完成觸發完成事件；掉線/取消觸發中斷事件

關鍵特性

• 角色對稱：發送/接收方皆可為客戶端或伺服器，共用同一流程
• 斷點續傳：自動偵測並啟動，可透過接收管理器屬性控制開關
• 自動執行緒管理：框架自動處理背景傳輸執行緒
• 雙向取消：任一方可隨時取消
• 事件通知：完成/中斷雙方皆收到事件

二、核心基礎設施

1. TransmittingFileInfo - 傳輸項目封裝

包含發送者/接收者 ID、檔名、檔案大小等資訊。部分屬性僅發送方有效（如 SendingFileParas），部分僅接收方有效（如 LocalSaveFilePath），部分支援斷點續傳（如 OriginFileLastUpdateTime）。

2. FileTransDisrupttedType - 中斷原因列舉

public enum FileTransDisrupttedType
{
    ActiveCancel,    // 主動取消
    DestCancel,      // 對方取消
    DestOffline,     // 對方掉線
    SelfOffline,     // 自己掉線/網路中斷
    DestReject,      // 對方拒絕
    OtherCause       // 其他（檔案讀取失敗等）
}

3. IFileTransferingEvents - 事件介面

public interface IFileTransferingEvents
{
    event CbGeneric FileTransStarted;
    event CbGeneric FileResumedTransStarted;
    event CbFileSendedProgress FileTransProgress;  // fileID, total, transferred
    event CbGeneric FileTransDisruptted;
    event CbGeneric FileTransCompleted;
}

注意：事件在背景執行緒觸發，更新 UI 需轉發至 UI 執行緒。

4. SendingFileParas - 發送參數控制

• SendingSpanInMSecs：發送頻率（毫秒），追求速度可設 0
• FilePackageSize：封包大小，網際網路建議 2048~4096，區域網路可設 204800+（可達 30MB/s+）

5. IFileController - 控制介面

public interface IFileController
{
    IFileTransferingEvents FileSendingEvents { get; }
    IFileTransferingEvents FileReceivingEvents { get; }
    
    void BeginSendFile(string accepterID, string filePath, string comment, out string fileID);
    void BeginSendFile(string accepterID, string filePath, string comment, SendingFileParas paras, out string fileID);
    void CancelFileTransfering(string fileID);
    void CancelFileTransferingAbout(string destUserID);
    TransmittingFileInfo GetFileInfo(string fileID);
}

方法詳解

• BeginSendFile：發起傳輸，fileID 為傳輸項目唯一標識（非檔案標識）。accepterID 可傳 NetServer.SystemUserID 直接發送給伺服器
• GetFileInfo：查詢任意進行中項目資訊
• CancelFileTransfering：取消指定項目並通知對方
• CancelFileTransferingAbout：批次取消與特定用戶相關的所有項目（如關閉聊天視窗前）
• FileSendingEvents/ReceivingEvents：暴露發送/接收端即時狀態

6. IFileHandler - 框架回呼介面

public interface IFileHandler : IBusinessHandler
{
    string ReadyToAcceptFile(string senderID, string fileName, long fileLength,
        string comment, string fileID, ResumedFileItem resumedFileItem);
    
    void OnResponseOfReceiver(TransmittingFileInfo info, bool agreed);
}

回呼詳解

• ReadyToAcceptFile：接收方被詢問是否同意。回傳儲存路徑表示同意（若 resumedFileItem 不為 null 且路徑相同則續傳），回傳 null 表示拒絕
• OnResponseOfReceiver：發送方收到對方回應。通常僅需通知使用者，後續傳輸由框架自動處理
• 兩方法皆在背景執行緒呼叫，操作 UI 需轉發

接收方同意後，相關事件將透過 IFileOutter 的 IFileTransferingEvents 依序觸發。