文档句柄非空、页数却是零——这是 FPDFAvail_GetDocument 在从未线性化的 PDF 上被调用时可能交回的东西,哪怕 FPDFAvail_IsDocAvail 已经报过 PDF_DATA_AVAIL。句柄看着像打开了,没有任何东西抱怨,查看器展示一份空文档。PDFium 的可用性 API 读的是 ISO 32000-1 附录 F 的线性化布局;其他任何文件都必须完整,并经普通的自定义文档路径打开。这个路由决定是边下载边打开的一半;另一半是那个在文件下了四分之一时关掉标签页、过一会儿又打开同一链接的用户
TPdfProgressiveDocument 背后的可用性循环
在 PDFium Component 里,整个会话活在 TPdfProgressiveDocument——一个 TPdf 子类——身上,它在随机访问流被填满的过程中保活一个 PDFium 可用性提供者。BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) 接受后备流和远端文件的逻辑大小(Content-Length,不是你本地存储的当前长度),接好一个 IsDataAvail 回调和一个 AddSegment 回调,然后调用 FPDFAvail_Create。OpenProgressiveDocument 成功之后,这个对象的行为与其他任何激活的 TPdf 无异:页面、文本、渲染、保存都走常规成员
每个解析步骤都是向你代码的一次提问。PDFium 要一个范围时,组件在该范围落在 AvailableByteCount 描述的连续前缀内、或落在已经经 RangeRequests 调度器完成的范围内时回答"有"。随后 OnDataAvailable 处理器拿到最后发言权,稀疏缓存靠它应答前两者都描述不了的范围。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 每次调用都要同一批范围,无界循环把一次网络故障变成卡死的界面。顺序之所以要紧,是因为调度器用临界区序列化自己的状态,但对后备存储上的 TStream.Position 什么都不做。传输线程必须先把响应字节写进流,再调 CompleteRequest——完成一发布,PDFium 可能立刻读那个范围。并发写方需要定位 I/O 或自己的锁
AvailableByteCount 为什么拒绝后退?
AvailableByteCount 只增不减。赋一个更小的值会抛 EPdfError,消息是"Available byte count cannot move backwards"——可用性回调一旦告诉 PDFium 某个范围存在,解析器可能已经从那里读出并缓存了对象;事后把那些字节拿走,PDFium 手里就攥着可用性回答矢口否认其来源的对象。同一个 setter 还拒绝大于 LogicalFileSize 的值,会话之外抛"No progressive load is active"
最后这条检查决定了你已经持有的字节算谁的。如果上一次访问把文件前 300 KB 留在了缓存里,就把这个数作为 AInitialAvailableByteCount 传入;组件在 FPDFAvail_Create 运行之前记下它,PDFium 第一次看文件头时就已见到。初始计数为零时,Linearization 在 PDFium 见到文件头之前读作 plnUnknown;这是正常的起始状态
抬高前缀还会取消工作。任何与刚公布字节重叠的在途请求都成了多余的,调度器把它丢掉并为其触发 OnCancelRequest;迟到的 CompleteRequest 对它返回 False。乱序填满的存储根本不该试图用前缀表达自己:经调度器完成范围,或在 OnDataAvailable 里逐范围应答。那个处理器里抛出的异常跨不过 C 回调边界,组件会捕获它并把该范围报为缺失,PDFium 下次检查时再问一遍就是
部分下载的 PDF 到底什么时候能打开?
只有线性化 PDF 能在整个文件到达之前打开。OpenProgressiveDocument 检查 Linearization 属性(plnUnknown、plnNotLinearized、plnLinearized)并挑选加载器。线性化文件在首页节和提示表就位后即可经 FPDFAvail_GetDocument 打开。非线性化文件走同一个文件访问记录上的 FPDF_LoadCustomDocument,而且这种文件要等每个字节都到位,PDFium 才报告文档可用。正是这个路由,把开头那个零页句柄挡在你的查看器之外
所以第一页出现得多快,由服务器上的文件决定。如果首屏时间要紧而发布侧归你管,就在那边把文件线性化。TPdf.SaveAsLinearized 能从组件本身写出附录 F 布局,Fast Web View 与提示表走查讲了那份布局里有什么。不归你管的文件,非线性化 PDF 依然经同一个循环加载;只是它要到 100% 才到达 pdaAvailable,而不是早早到达
LoadAvailablePage 接受从 1 起算的页码,并保持 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,什么都不碰,worker 因此不必知道自己的范围为何过期
CancelProgressiveLoad 释放什么,按什么顺序?
CancelProgressiveLoad 用四步拆掉一个会话,顺序不可调换:取消范围调度器、关闭文档、用 FPDFAvail_Destroy 销毁可用性句柄、最后释放回调记录和流适配器。先取消调度器会推进它的代计数器、丢掉每个待处理和在途请求,并对每个在途请求触发 OnCancelRequest。之后才抵达的传输完成携带旧代数,CompleteRequest 返回 False。文档先于可用性句柄和流适配器关闭,因为 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,worker 停下之后自己释放流。交出所有权意味着取消会在一笔已在途的写可能还在路上时释放流。只要碰存储的线程不止调用者一个,就保留所有权;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 的 byte range 加载。停掉一个已到达页面的慢速渲染是另一套机制,见 可取消的渐进页面渲染。TPdfProgressiveDocument、它的范围调度器和 SaveAsLinearized 都属于 PDFium Component for Delphi and C++Builder