Ein Document-Handle ungleich null mit einer Seitenanzahl von null ist das, was FPDFAvail_GetDocument zurückgeben kann, wenn man es auf eine PDF ansetzt, die nie linearisiert wurde, selbst nachdem FPDFAvail_IsDocAvail PDF_DATA_AVAIL gemeldet hat. Das Handle sieht geöffnet aus, nichts beschwert sich, und der Viewer zeigt ein leeres Dokument. PDFiums Availability-API liest das linearisierte Layout aus ISO 32000-1 Anhang F; jede andere Datei muss vollständig sein und über den gewöhnlichen Custom-Document-Pfad geöffnet werden. Diese Routing-Entscheidung ist die Hälfte davon, eine PDF während des Downloads zu öffnen. Die andere Hälfte ist der Benutzer, der das Tab bei einem Viertel der Datei schließt und denselben Link einen Moment später erneut öffnet
Die Availability-Schleife hinter TPdfProgressiveDocument
In der PDFium Component lebt die ganze Sitzung in TPdfProgressiveDocument, einer TPdf-Unterklasse, die einen PDFium-Availability-Provider am Leben hält, während ein Random-Access-Stream sich füllt. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) nimmt den tragenden Stream und die logische Größe der entfernten Datei (den Content-Length, nicht die aktuelle Länge Ihres lokalen Speichers), verkabelt einen IsDataAvail-Callback und einen AddSegment-Callback und ruft FPDFAvail_Create. Sobald OpenProgressiveDocument gelingt, verhält sich das Objekt wie jedes andere aktive TPdf: Seiten, Text, Rendering und Speichern laufen alle über die üblichen Member
Jeder Parse-Schritt ist eine Frage an Ihren Code. Will PDFium einen Bereich, antwortet die Komponente mit Ja, wenn der Bereich innerhalb des zusammenhängenden Präfix liegt, das AvailableByteCount beschreibt, oder innerhalb eines Bereichs, der bereits über den RangeRequests-Scheduler abgeschlossen wurde. Ein OnDataAvailable-Handler bekommt dann das letzte Wort, so beantwortet ein Sparse-Cache Bereiche, die keine der beiden beschreiben können. CheckDocumentAvailability liefert einen von drei TPdfDataAvailability-Werten (pdaAvailable, pdaNotAvailable, pdaError) und gibt die Byte-Bereiche, die PDFium angefragt hat, als sortiertes, verschmolzenes TPdfDownloadRanges-Array zurück. Diese Bereiche sind bereits im Scheduler bei rrpImmediate-Priorität eingereiht, bis Sie sie sehen, also ist das Hint-Array für Logging und Fortschrittsanzeige da; die Arbeits-Warteschlange ist RangeRequests
// FetchRange ist Ihr Transport (HTTP-Range-GET, Socket, Blob-Reader):
// er schreibt Size Bytes an Offset in Store und liefert, wie viele ankamen
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;
// Die Hints sind bereits eingereiht; erst die Bytes schreiben, dann abschließen
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;
Zwei Details in dieser Schleife tragen Gewicht. Das Rundenlimit existiert, weil ein toter Link CheckDocumentAvailability bei jedem Aufruf nach denselben Bereichen fragen lässt, und eine unbegrenzte Schleife verwandelt einen Netzwerkfehler in eine hängende UI. Die Reihenfolge zählt, weil der Scheduler seinen eigenen Zustand mit einer kritischen Sektion serialisiert, aber nichts für TStream.Position auf dem Backing-Store tut. Ein Transport-Thread muss die Antwort-Bytes in den Stream schreiben, bevor er CompleteRequest aufruft, denn PDFium kann den Bereich lesen, sobald die Fertigstellung veröffentlicht wird. Gleichzeitige Schreiber brauchen positionierte I/O oder ein eigenes Lock
Warum weigert sich AvailableByteCount, rückwärts zu gehen?
AvailableByteCount wächst nur. Einen kleineren Wert zuzuweisen wirft eine EPdfError mit „Available byte count cannot move backwards“, denn sobald der Availability-Callback PDFium gesagt hat, dass ein Bereich existiert, hat der Parser daraus möglicherweise bereits Objekte gelesen und gecacht. Diese Bytes nachträglich wegzunehmen würde PDFium mit Objekten zurücklassen, deren Quelle die Availability-Antworten jetzt leugnen. Derselbe Setter weist Werte über LogicalFileSize hinaus zurück und wirft außerhalb einer Sitzung „No progressive load is active“
Diese letzte Prüfung entscheidet, wohin Bytes gehören, die Sie bereits halten. Hat ein früherer Besuch die ersten 300 KB der Datei in einem Cache hinterlassen, übergeben Sie diese Anzahl als AInitialAvailableByteCount; die Komponente hält sie fest, bevor FPDFAvail_Create läuft, also sieht PDFiums erster Blick auf den Header sie bereits. Mit einer Anfangsanzahl von null liest Linearization plnUnknown, bis PDFium den Header gesehen hat; das ist der normale Startzustand
Das Anheben des Präfix bricht außerdem Arbeit ab. Jede laufende Anfrage, die sich mit den neu angekündigten Bytes überlappt, ist jetzt redundant, also verwirft sie der Scheduler und feuert dafür OnCancelRequest; ein spätes CompleteRequest für diese Anfrage liefert False. Ein Speicher, der durcheinander füllt, sollte gar nicht versuchen, sich über das Präfix auszudrücken. Schließen Sie die Bereiche über den Scheduler ab, oder antworten Sie pro Bereich in OnDataAvailable. Eine Exception, die in diesem Handler geworfen wird, kann die C-Callback-Grenze nicht überqueren, also fängt die Komponente sie ab und meldet den Bereich als fehlend, und PDFium fragt bei der nächsten Prüfung einfach wieder
Wann kann ein teilweise heruntergeladenes PDF tatsächlich öffnen?
Nur eine linearisierte PDF öffnet sich, bevor die ganze Datei angekommen ist. OpenProgressiveDocument prüft die Eigenschaft Linearization (plnUnknown, plnNotLinearized, plnLinearized) und wählt den Loader. Eine linearisierte Datei öffnet über FPDFAvail_GetDocument, sobald der First-Page-Abschnitt und die Hint-Tabellen vorhanden sind. Eine nicht linearisierte Datei geht über FPDF_LoadCustomDocument auf demselben File-Access-Record, und für so eine Datei meldet PDFium das Dokument erst als verfügbar, wenn jedes Byte da ist. Genau dieses Routing hält das Null-Seiten-Handle aus dem Eingangsabsatz aus Ihrem Viewer fern
Also entscheidet die Datei auf dem Server, wie schnell die erste Seite erscheint. Wenn Ihnen Zeit bis zum ersten Frame wichtig ist und Sie die veröffentlichende Seite kontrollieren, linearisieren Sie die Dateien dort. TPdf.SaveAsLinearized schreibt das Anhang-F-Layout aus der Komponente heraus, und der Fast-Web-View- und Hint-Tabellen-Walkthrough behandelt, was dieses Layout enthält. Für Dateien, die Sie nicht kontrollieren, lädt eine nicht linearisierte PDF weiterhin durch dieselbe Schleife; sie erreicht pdaAvailable nur bei 100 Prozent statt früh
LoadAvailablePage nimmt eine 1-basierte Seitennummer und hält die Reihenfolge ein, die PDFium erwartet. Vor der ersten Seitenprüfung läuft CheckFormAvailability, das FPDFAvail_IsFormAvail umhüllt, und erst danach ruft es FPDFAvail_IsPageAvail. Ein Ergebnis von pfaNotPresent ist die normale Antwort für ein Dokument ohne AcroForm und blockiert nichts. Ist die Seite bereit, macht LoadAvailablePage sie zur aktiven Seite, also kann ein Viewer Seite 1 einer linearisierten Broschüre rendern, während spätere Seiten noch unterwegs sind. Das Seitenwarten hat dieselbe Gestalt wie das erste Listing: LoadAvailablePage aufrufen, bei pdaNotAvailable RangeRequests abarbeiten, bei pdaAvailable oder pdaError stoppen, und ein Rundenlimit halten. FirstAvailablePageNumber meldet die Seite, die das Linearisierungs-Dictionary als erste benennt, bereits umgerechnet aus PDFiums nullbasiertem Index. Bei einer nicht linearisierten Datei meldet jede Seite sofort pdaAvailable, denn das Dokument konnte sich erst öffnen, als die Datei vollständig war
Wiederholungen, kurze Leseaktionen und Prioritäten im Range-Scheduler
Die FPDFAvail_*-API selbst weiß nichts über Netzwerke. Sie sagt, welche Bytes der Parser gerade braucht, und fragt später erneut; es gibt keinen Begriff einer Anfrage, einer Wiederholung oder eines Abbruchs. TPdfRangeRequestScheduler liefert das, und vier seiner Regeln prägen, wie Sie den Transport schreiben
- Eine kurze Antwort gilt als Fortschritt.
CompleteRequest(Request, BytesReceived)mit weniger Bytes als angefragt veröffentlicht das Präfix und reiht den Rest ein. Die kurze Antwort zählt auch als gescheiterter Versuch, also bleibt der Rest anMaxRetryCountgebunden und wird aufgegeben, sobald das erschöpft ist; null Bytes sind ein schlicht gescheiterter Versuch MaxRetryCountdefaultet auf 2, also bekommt ein Bereich insgesamt drei Versuche.FailRequestliefertTrue, wenn er den Bereich neu eingereiht hat, undFalse, sobald der Bereich aufgegeben ist;Statistics.AbandonedRequestCountverfolgt, wie viele aufgegeben habenMaxRequestSizeteilt große Bereiche zur Dequeue-Zeit in Chunks, undMergeGaplässt zwei wartende Bereiche über eine kleine unbekannte Lücke verschmelzen, aber nie über Bytes, die bereits abgeschlossen oder unterwegs sind- Hints von
CheckDocumentAvailabilityundLoadAvailablePagekommen beirrpImmediatean. Form-Hints von einem direktenCheckFormAvailability-Aufruf kommen beirrpNormalan; wennLoadAvailablePagediese Prüfung selbst ausführt und die Formdaten fehlen, werden die Hints beirrpImmediateeingereiht.TryDequeuebedient immer zuerst die höchste Priorität und innerhalb einer Priorität den niedrigsten Offset
Die Prioritätsregel zahlt sich aus, wenn Sie Prefetch betreiben. Reihen Sie die ganze Datei direkt nach dem Öffnen des Dokuments bei rrpBackground ein, und der Scheduler zieht alles bereits Abgeschlossene oder Unterwegs-Seiende ab, also gehen nur die fehlenden Bytes über die Leitung. Springt der Benutzer dann zu Seite 40 und der Hint dieser Seite überlappt einen Hintergrund-Chunk, der bereits herunterlädt, zieht der Scheduler die Hintergrund-Anfrage zurück, feuert dafür OnCancelRequest, stellt die nicht überlappenden Enden ohne berechneten Versuch wieder auf Hintergrund-Priorität und reiht die Überlappung als frische Immediate-Arbeit ein. Der Sprung gewinnt die Verbindung. Ohne das müsste die Seitenanfrage hinter einem 256-KB-Chunk warten, der sie nicht interessiert
procedure TDownloadForm.QueueRestOfFile;
var
Whole: TPdfDownloadRanges;
begin
FPdf.RangeRequests.MaxRequestSize := 256 * 1024; // Die Chunk-Größe ist Ihre Entscheidung
SetLength(Whole, 1);
Whole[0].Offset := 0;
Whole[0].Size := FPdf.LogicalFileSize;
FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;
// Auf einem Worker-Thread aufgerufen, wenn eine HTTP-Range-Antwort fertig ist.
// WriteAt ist Ihre eigene positionierte Schreiboperation in den Backing-Store
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); // zuerst die Bytes
FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
end
else if not FPdf.RangeRequests.FailRequest(Request) then
TThread.Queue(nil, ShowRangeGaveUp); // aufgegeben, oder aus einer abgebrochenen Sitzung
end;
Sowohl CompleteRequest als auch FailRequest sind gefahrlos aus dem Worker-Thread aufzurufen; der Scheduler nimmt sein eigenes Lock. Eine Anfrage, die überholt wurde oder zu einer abgebrochenen Sitzung gehört, kommt als False zurück, ohne irgendetwas anzufassen, also muss der Worker nicht wissen, warum sein Bereich veraltet ist
Was gibt CancelProgressiveLoad frei, und in welcher Reihenfolge?
CancelProgressiveLoad baut eine Sitzung in vier Schritten ab, immer in derselben Reihenfolge: den Range-Scheduler abbrechen, das Dokument schließen, das Availability-Handle mit FPDFAvail_Destroy zerstören, dann die Callback-Records und den Stream-Adapter freigeben. Den Scheduler zuerst abzubrechen erhöht seinen Generationszähler, verwirft jede wartende und laufende Anfrage und feuert für jede laufende OnCancelRequest. Eine Transport-Fertigstellung, die danach landet, trägt die alte Generation, und CompleteRequest liefert False. Das Dokument schließt, bevor das Availability-Handle und der Stream-Adapter verschwinden, weil PDFium während des Schließens eines Dokuments noch durch den File-Access-Provider lesen kann
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
FPdf := TPdfProgressiveDocument.Create(nil);
// Der Scheduler lebt so lang wie FPdf, also einmal verdrahten
FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;
procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
Attempt: Cardinal);
begin
FTransport.Abort(RequestId); // Ihr Code: diesen Socket oder Request schließen
end;
procedure TDownloadForm.CancelButtonClick(Sender: TObject);
begin
FPdf.CancelProgressiveLoad;
// ProgressiveLoading = False, Active = False, AvailableByteCount = 0
end;
Die Methode ist idempotent und dient als einzelner Aufräum-Pfad für drei Situationen: ein BeginProgressiveLoad, das mitten im Aufbau scheitert, ein expliziter Benutzer-Abbruch und der Destruktor. BeginProgressiveLoad ruft sie ebenfalls auf, also ist dasselbe Objekt auf einer neuen URL neu zu starten in Ordnung, solange die frühere Sitzung nie bis zum Öffnen kam. Sobald OpenProgressiveDocument gelungen ist, ist das Objekt aktiv, und BeginProgressiveLoad wirft den üblichen Fehler „Cannot perform this operation on an active“; rufen Sie zuerst CancelProgressiveLoad auf. OnCancelRequest ist außerdem der einzige Ort, an dem Ihre Sockets geschlossen werden, denn der Scheduler hat keine Vorstellung davon, was ein Socket ist. Exceptions, die darin geworfen werden, werden pro Anfrage geschluckt, also kann ein scheiternder Abbruch den Rest nicht blockieren
Wer den Store schreibt, entscheidet, wem er gehört. Mit einem Worker-Thread, der in den tragenden Stream schreibt, übergeben Sie AOwnsStream = False und geben den Stream selbst frei, nachdem der Worker gestoppt hat. Die Eigentümerschaft abzugeben bedeutet, dass der Abbruch den Stream freigibt, während ein Schreibvorgang, der bereits läuft, möglicherweise noch unterwegs ist. Behalten Sie die Eigentümerschaft, wann immer ein anderer Thread als der Aufrufer den Store anfasst; AOwnsStream = True passt nur zu einem vollständig synchronen Transport wie im ersten Listing
Features, die auf die ganze Datei warten
Manche Features brauchen die ursprünglichen Datei-Bytes, nicht das geparste Dokument, und sie lehnen eine unvollständige progressive Quelle rundheraus ab. ReadXmpPacket wirft „PDF/A metadata is unavailable until progressive loading completes“. ValidatePades liefert ein Ergebnis, dessen SourceStatus pvssIncomplete ist, und ValidatePdfMac meldet nicht unterstützt mit einer Meldung, die nach der vollständigen Quelle fragt. BeginIncrementalSave scheitert ebenfalls, denn ein Incremental-Update muss an genau die Bytes anhängen, die geladen wurden
Der Vollständigkeits-Test hinter allen ihnen ist AvailableByteCount, das LogicalFileSize erreicht. Ein Transport, der alles über den Scheduler liefert, kann also jedes Byte halten und trotzdem hören, die Quelle sei unvollständig, weil das zusammenhängende Präfix sich nie bewegt hat. Veröffentlichen Sie das Präfix, sobald der Scheduler die volle Abdeckung bestätigt:
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); // Ihre UI
end;
Eine Größenbeschränkung greift, bevor irgendetwas davon beginnt. Auf Windows speichert FPDF_FILEACCESS die Dateilänge in einem 32-Bit-Feld, also weist BeginProgressiveLoad eine logische Größe über 4 GiB mit einer EPdfError zurück, statt PDFium eine abgeschnittene Länge parsen zu lassen
Für das Laden einer vollständigen lokalen Datei auf Bedarf über einen Stream-Adapter siehe große PDFs auf Bedarf mit PDFium streamen; für eine PDF, die in einem größeren Buffer sitzt, siehe Byte-Range-Laden für eingebettete PDFs. Einen langsamen Render einer bereits angekommenen Seite zu stoppen ist ein anderer Mechanismus, behandelt in abbrechbares progressives Seitenrendering. TPdfProgressiveDocument, sein Range-Scheduler und SaveAsLinearized sind Teil der PDFium Component für Delphi und C++Builder