文件 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 或自己的鎖
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 擋在你的檢視器外面
所以第一頁出現得多快,由伺服器上那份檔案決定。首屏時間要緊、發布端又在你手裡,就在那裡把檔案線性化。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 關文件的過程中仍可能透過檔案存取提供者讀取
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 的一部分