Technischer Artikel

PDFium Progressive Download und Cancel in Delphi (FPDFAvail)

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

Die Availability-Schleife von TPdfProgressiveDocument in PDFium Component: BeginProgressiveLoad erzeugt den FPDFAvail-Provider, CheckDocumentAvailability gibt sortierte, verschmolzene Download-Hints mit rrpImmediate-Priorität zurück, der Transport schreibt Bytes in den Store, bevor CompleteRequest jeden Bereich an PDFium veröffentlicht, und die Schleife ist bei 64 Runden gedeckelt, weil ein toter Link immer wieder nach denselben Bereichen fragt
Erst die Bytes schreiben, dann die Anfrage abschließen: In dem Moment, in dem eine Fertigstellung veröffentlicht wird, darf PDFium diesen Bereich lesen, und nichts schützt die Stream-Position für Sie

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

Wie OpenProgressiveDocument in PDFium Component einen Teil-Download routet: Eine linearisierte Datei öffnet über FPDFAvail_GetDocument, sobald First-Page-Abschnitt und Hint-Tabellen ankommen, eine nicht linearisierte braucht FPDF_LoadCustomDocument und jedes Byte, und LoadAvailablePage prüft die Form-Verfügbarkeit mit FPDFAvail_IsFormAvail vor dem Seitencheck und vermeidet damit die Nicht-null-Null-Seiten-Handle-Falle
Nur linearisierte Dateien bekommen einen Vorsprung; bei allem anderen kann FPDFAvail_GetDocument ein offenaussehendes Dokument mit null Seiten liefern – genau das verhindert das Routing

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 an MaxRetryCount gebunden und wird aufgegeben, sobald das erschöpft ist; null Bytes sind ein schlicht gescheiterter Versuch
  • MaxRetryCount defaultet auf 2, also bekommt ein Bereich insgesamt drei Versuche. FailRequest liefert True, wenn er den Bereich neu eingereiht hat, und False, sobald der Bereich aufgegeben ist; Statistics.AbandonedRequestCount verfolgt, wie viele aufgegeben haben
  • MaxRequestSize teilt große Bereiche zur Dequeue-Zeit in Chunks, und MergeGap lässt zwei wartende Bereiche über eine kleine unbekannte Lücke verschmelzen, aber nie über Bytes, die bereits abgeschlossen oder unterwegs sind
  • Hints von CheckDocumentAvailability und LoadAvailablePage kommen bei rrpImmediate an. Form-Hints von einem direkten CheckFormAvailability-Aufruf kommen bei rrpNormal an; wenn LoadAvailablePage diese Prüfung selbst ausführt und die Formdaten fehlen, werden die Hints bei rrpImmediate eingereiht. TryDequeue bedient 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

Die feste Abbau-Reihenfolge von CancelProgressiveLoad in PDFium Component: Erst den Range-Scheduler abbrechen, damit späte Fertigstellungen auf den erhöhten Generationszähler treffen und False liefern, das Dokument schließen, bevor der File-Access-Adapter verschwindet, das Availability-Handle mit FPDFAvail_Destroy zerstören und erst dann die Callback-Records entsorgen und den Stream-Adapter freigeben
Eine idempotente Methode räumt einen gescheiterten Start, einen Nutzer-Abbruch und den Destruktor gleichermaßen auf; schreibt ein Worker-Thread in den Store, bleibt die Stream-Ownership bei Ihnen
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