技術文章

在 Delphi 用 PDFium 做漸進下載與取消(FPDFAvail)

文件 handle 非空、頁數為零——這就是 FPDFAvail_GetDocument 在一份從未線性化的 PDF 上的可能產出,哪怕 FPDFAvail_IsDocAvail 已回報 PDF_DATA_AVAIL。handle 看似開著、無人報錯、檢視器端出一個空文件。PDFium 的可用性 API 讀的是 ISO 32000-1 附錄 F 的線性化版面;其他任何檔案都必須等到完整、走普通的自訂文件路徑開啟。這個分流決策是「下載中開 PDF」的一半;另一半是那個在下載到四分之一時關掉分頁、過一會兒又點開同一個連結的使用者

TPdfProgressiveDocument 背後的可用性迴圈

PDFium Component 裡,整個工作階段住在 TPdfProgressiveDocument——一個 TPdf 子類,在隨機存取串流逐漸填滿的同時保住 PDFium 的可用性提供者。BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) 收後備串流與遠端檔案的邏輯大小(是 Content-Length,不是你本地倉庫的當前長度),接上 IsDataAvail 回呼與 AddSegment 回呼,並呼叫 FPDFAvail_Create。OpenProgressiveDocument 成功之後,這個物件的表現就跟任何現役 TPdf 一樣:頁面、文字、渲染與存檔全走平常的成員

解析的每一步都是對你程式碼的提問。PDFium 要一個範圍時,元件在範圍落在 AvailableByteCount 描述的連續前綴內、或落在 RangeRequests 排程器已完成的範圍內時回答有。OnDataAvailable handler 隨後拿到最終發言權——稀疏快取就是靠它回答那兩者都描述不了的範圍。CheckDocumentAvailability 回傳三個 TPdfDataAvailability 值之一(pdaAvailable、pdaNotAvailable、pdaError),並把 PDFium 要的位元組範圍以排序合併的 TPdfDownloadRanges 陣列交回。你看到這些範圍時,它們已經以 rrpImmediate 優先權排在排程器上,所以提示陣列是給日誌與進度顯示用的;工作佇列是 RangeRequests

// FetchRange 是您的傳輸層(HTTP Range GET、socket、blob 讀取器):
// 把 Size 個位元組寫進 Store 的 Offset 處,回傳實際送達多少
function FetchRange(Store: TStream; Offset, Size: UInt64): UInt64; forward;

procedure OpenWhileDownloading(Pdf: TPdfProgressiveDocument; Store: TStream;
  RemoteSize: UInt64);
const
  MaxRounds = 64;
var
  Hints: TPdfDownloadRanges;
  State: TPdfDataAvailability;
  Request: TPdfRangeRequest;
  Round: Integer;
begin
  Pdf.BeginProgressiveLoad(Store, RemoteSize, False);
  State := pdaNotAvailable;
  for Round := 1 to MaxRounds do
  begin
    State := Pdf.CheckDocumentAvailability(Hints);
    if State <> pdaNotAvailable then
      Break;
    // 提示已排入佇列;先寫位元組,再完成請求
    while Pdf.RangeRequests.TryDequeue(Request) do
      Pdf.RangeRequests.CompleteRequest(Request,
        FetchRange(Store, Request.Offset, Request.Size));
  end;
  if State <> pdaAvailable then
    raise EPdfError.Create('The document could not be discovered');
  Pdf.OpenProgressiveDocument;
end;

這個迴圈裡有兩個細節有分量。輪數上限的存在,是因為斷掉的連結會讓 CheckDocumentAvailability 每次呼叫都要同樣的範圍,無上限迴圈會把網路故障變成掛死的 UI。順序之所以要緊,是因為排程器用自己的 critical section 保護自身狀態,卻對後備儲存上的 TStream.Position 什麼都不做。傳輸執行緒必須把回應位元組寫進串流之後才呼叫 CompleteRequest,因為完成一發布,PDFium 可能立刻讀那個範圍。並發寫入者需要定址 I/O 或自己的鎖

PDFium Component 裡 TPdfProgressiveDocument 的可用性迴圈:BeginProgressiveLoad 建 FPDFAvail 提供者,CheckDocumentAvailability 回傳排序合併、以 rrpImmediate 優先權排隊的下載提示,傳輸層先寫位元組進儲存、CompleteRequest 才把範圍發布給 PDFium;迴圈上限 64 輪,因為斷掉的連結會一直要同樣的範圍
先寫位元組,再完成請求:完成一發布,PDFium 隨時可能讀那個範圍,串流位置沒有人替你保護

AvailableByteCount 為什麼拒絕後退?

AvailableByteCount 只增不減。指派更小的值會丟帶「Available byte count cannot move backwards」的 EPdfError,因為可用性回呼一旦告訴 PDFium 某範圍存在,解析器可能已經從那裡讀取並快取了物件;事後把那些位元組收走,PDFium 手上就握著可用性回答現在否認其來源的物件。同一個 setter 也拒絕大於 LogicalFileSize 的值,並在工作階段外丟「No progressive load is active」

最後那個檢查決定了手裡已有的位元組歸誰。上次造訪在快取裡留下檔案前 300 KB 的話,把這個數當 AInitialAvailableByteCount 傳入;元件在 FPDFAvail_Create 跑之前記下它,PDFium 第一眼看檔頭就看得見。初始計數為零時,Linearization 在 PDFium 看過檔頭之前讀作 plnUnknown——那是正常的起點

抬高前綴同樣會取消工作。任何與新公布位元組重疊的在途請求都成了多餘,排程器把它丟棄並為它觸發 OnCancelRequest;遲到的 CompleteRequest 對它回傳 False。亂序填滿的儲存根本不該試圖透過前綴表達自己——範圍走排程器完成,或在 OnDataAvailable 裡逐範圍回答。在那個 handler 裡丟出的例外無法穿過 C 回呼邊界,元件會抓住它、把該範圍回報為缺失,PDFium 下次檢查再問一遍

部分下載的 PDF 到底什麼時候能開?

只有線性化 PDF 能在整個檔案到位之前打開。OpenProgressiveDocument 檢查 Linearization 屬性(plnUnknown、plnNotLinearized、plnLinearized)並挑選載入器。線性化檔案在首頁區段與提示表到位後就能經 FPDFAvail_GetDocument 開啟。非線性化檔案走同一份檔案存取記錄上的 FPDF_LoadCustomDocument,而且對這種檔案,PDFium 要到每個位元組都在才回報文件可用。正是這個分流,把開場那段零頁 handle 擋在你的檢視器外面

OpenProgressiveDocument 在 PDFium Component 裡如何分流部分下載:線性化檔案在首頁區段與提示表到位後經 FPDFAvail_GetDocument 開啟;非線性化檔案要走 FPDF_LoadCustomDocument 且需要每個位元組;LoadAvailablePage 在檢查頁面前先以 FPDFAvail_IsFormAvail 檢查表單可用性,避開非空零頁 handle 的陷阱
只有線性化檔案搶得到先機;其他檔案上 FPDFAvail_GetDocument 可能回傳看似已開、頁數為零的文件——分流正是為了擋這個

所以第一頁出現得多快,由伺服器上那份檔案決定。首屏時間要緊、發布端又在你手裡,就在那裡把檔案線性化。TPdf.SaveAsLinearized 直接從元件寫出附錄 F 版面,內容見Fast Web View 與提示表走查。不受你控制的檔案,非線性化 PDF 照樣經同一個迴圈載入;只是它要到 100% 才抵達 pdaAvailable,而不是提前

LoadAvailablePage 收一基起算的頁碼,並維持 PDFium 期待的順序:第一次頁面檢查之前先跑 CheckFormAvailability(包著 FPDFAvail_IsFormAvail),然後才呼叫 FPDFAvail_IsPageAvail。pfaNotPresent 是沒有 AcroForm 的文件得到的正常答案,什麼也不擋。頁面就緒後,LoadAvailablePage 把它設為現用頁,檢視器於是能在後續頁面還在路上的時候渲染線性化簡報的第 1 頁。頁面等待與第一段範例同一個形狀:呼叫 LoadAvailablePage,pdaNotAvailable 就排空 RangeRequests,pdaAvailable 或 pdaError 就停,並保留輪數上限。FirstAvailablePageNumber 回報線性化字典指定的首頁,已從 PDFium 的零起點索引換算過。非線性化檔案的每一頁都立刻回報 pdaAvailable,因為文件只有等檔案完整才開得起來

範圍排程器裡的重試、短讀與優先權

FPDFAvail_* API 本身對網路一無所知:它說出解析器現在需要哪些位元組,晚點再問;沒有請求、重試或取消的概念。TPdfRangeRequestScheduler 補上這些,它的四條規則決定了你怎麼寫傳輸層

  • 短回應算進展。CompleteRequest(Request, BytesReceived) 收到的位元組少於請求時,公布前綴、把剩餘重新排隊。短回應同時計一次失敗嘗試,剩餘部分照樣受 MaxRetryCount 約束,次數用完即棄;零位元組就是一次普通的失敗嘗試
  • MaxRetryCount 預設 2,一個範圍總共三次機會。FailRequest 重新排隊時回傳 True,範圍被放棄時回傳 False;Statistics.AbandonedRequestCount 追蹤放棄了多少
  • MaxRequestSize 在出隊時把大範圍切塊;MergeGap 讓兩個待處理範圍跨過小的未知間隙合併,但絕不跨過已完成或在途的位元組
  • CheckDocumentAvailability 與 LoadAvailablePage 的提示以 rrpImmediate 到達;直接呼叫 CheckFormAvailability 得到的表單提示以 rrpNormal 到達,而 LoadAvailablePage 自己跑那個檢查、表單資料又缺席時,提示以 rrpImmediate 排隊。TryDequeue 永遠先服務最高優先權、同優先權內先服務最低偏移

預取時優先權規則就發威了。文件一開就把整個檔案以 rrpBackground 排隊,排程器會扣掉已完成與在途的部分,只有缺的位元組上網路。使用者隨後跳到第 40 頁、該頁提示與某個下載中的背景塊重疊時,排程器抽回背景請求、為它觸發 OnCancelRequest、把不重疊的尾段以背景優先權放回(不計重試),並把重疊部分當成全新的即時工作排隊。跳頁贏得連線。沒有這一層,頁面請求就得排在一個它根本不關心的 256 KB 塊後面

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // 分塊大小由你定
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// 一個 HTTP Range 回應完成時在工作執行緒上呼叫。
// WriteAt 是你自己的定址寫入,目標是後備儲存
procedure TDownloadForm.RangeFinished(const Request: TPdfRangeRequest;
  const Body: TBytes; Succeeded: Boolean);
begin
  if Succeeded and (Length(Body) > 0) then
  begin
    WriteAt(FStore, Request.Offset, Body);              // 位元組先行
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // 已放棄,或來自已取消的工作階段
end;

CompleteRequest 與 FailRequest 從工作執行緒呼叫都安全,排程器自己拿鎖。被取代或屬於已取消工作階段的請求回傳 False、什麼也不碰,工作執行緒因此不必知道自己的範圍為什麼過期了

CancelProgressiveLoad 釋放什麼,按什麼順序?

CancelProgressiveLoad 分四步拆除工作階段,順序永遠相同:取消範圍排程器、關閉文件、以 FPDFAvail_Destroy 銷毀可用性 handle,然後釋放回呼記錄與串流配接器。先取消排程器會推進它的 generation 計數器、丟棄所有待處理與在途請求,並為每個在途請求觸發 OnCancelRequest。之後才抵達的傳輸完成帶著舊 generation,CompleteRequest 回傳 False。文件在可用性 handle 與串流配接器消失之前關閉,因為 PDFium 關文件的過程中仍可能透過檔案存取提供者讀取

PDFium Component 裡 CancelProgressiveLoad 的固定拆除順序:先取消範圍排程器,遲到的完成撞上升代的 generation 計數器回傳 False;在檔案存取配接器消失前關閉文件;以 FPDFAvail_Destroy 銷毀可用性 handle;最後才釋放回呼記錄與串流配接器
一個冪等方法同時收拾啟動失敗、使用者取消與解構子三種情況;有工作執行緒往儲存寫入時,串流所有權留在你手上
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // 排程器與 FPdf 同壽,掛一次就好
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // 你的程式碼:關掉那個 socket 或請求
end;

procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
  FPdf.CancelProgressiveLoad;
  // ProgressiveLoading = False、Active = False、AvailableByteCount = 0
end;

這個方法是冪等的,同時充當三種情況的唯一清理路徑:BeginProgressiveLoad 建到一半失敗、使用者明確取消、以及解構子。BeginProgressiveLoad 自己也會呼叫它,所以前一個工作階段還沒走到開啟那步時,同一個物件換新 URL 重來沒問題。OpenProgressiveDocument 成功之後物件就是現役的,再呼叫 BeginProgressiveLoad 會丟平常那個「Cannot perform this operation on an active」錯誤——先呼叫 CancelProgressiveLoad。OnCancelRequest 也是你的 socket 唯一被關閉的地方,排程器根本不知道 socket 為何物。它裡面丟的例外按請求吞掉,一個失敗的 abort 擋不住其餘

誰寫儲存,誰就該持有它。有工作執行緒往後備串流寫入時,傳 AOwnsStream = False,等工作者停了再自己釋放串流。交出所有權意味著取消時串流被釋放,而一筆已在途的寫入可能還在路上。只要碰儲存的執行緒不是呼叫者,就保留所有權;AOwnsStream = True 只適合第一段範例那種完全同步的傳輸

等整份檔案的功能

有些功能需要原始檔案位元組而不是解析後的文件,對不完整的漸進來源一律直接拒絕。ReadXmpPacket 丟「PDF/A metadata is unavailable until progressive loading completes」;ValidatePades 回傳 SourceStatus 為 pvssIncomplete 的結果;ValidatePdfMac 回報不支援、訊息要求完整來源;BeginIncrementalSave 同樣失敗,因為增量更新必須附加在載入時的精確位元組上

它們背後的完整性測試是同一個:AvailableByteCount 抵達 LogicalFileSize。全部位元組都經排程器交付的傳輸,因此可能手握每個位元組卻仍被判定來源不完整——連續前綴從沒動過。排程器確認全覆蓋之後,把前綴發布出去:

procedure TDownloadForm.CheckSignaturesWhenComplete;
var
  Report: TPadesValidationResult;
begin
  if FPdf.RangeRequests.IsRangeAvailable(0, FPdf.LogicalFileSize) then
    FPdf.AvailableByteCount := FPdf.LogicalFileSize;
  Report := FPdf.ValidatePades;
  if Report.SourceStatus = pvssIncomplete then
    LabelStatus.Caption := 'Signatures are checked when the download finishes'
  else
    ShowSignatureReport(Report);   // 你的 UI
end;

這一切開始之前有一條尺寸上限。Windows 上 FPDF_FILEACCESS 以 32 位元欄位存檔案長度,所以 BeginProgressiveLoad 對超過 4 GiB 的邏輯大小直接丟 EPdfError,不讓 PDFium 去解析一個被截斷的長度

按需經串流配接器載入完整的本地檔案,見以 PDFium 隨需串流大型 PDF;PDF 嵌在更大緩衝區裡的情況,見嵌入式 PDF 的位元組範圍載入。停掉已到位頁面的慢渲染是另一套機制,見可取消的漸進頁面渲染。TPdfProgressiveDocument、它的範圍排程器與 SaveAsLinearized 都是PDFium Component for Delphi and C++Builder 的一部分