Technisch artikel

Progressief downloaden en annuleren met PDFium in Delphi

Een documenthandle ongelijk nul met een pagina-aantal van nul is wat FPDFAvail_GetDocument kan teruggeven wanneer hij wordt aangeroepen op een PDF die nooit is gelinieariseerd, zelfs nadat FPDFAvail_IsDocAvail PDF_DATA_AVAIL heeft gemeld. De handle ziet er open uit, niets moppert, en de viewer toont een leeg document. De availability-API van PDFium leest de gelinieariseerde indeling van ISO 32000-1 Bijlage F; elk ander bestand moet compleet zijn en via het gewone custom-documentpad worden geopend. Die routeringsbeslissing is de helft van wat een PDF tijdens het downloaden openen inhoudt. De andere helft is de gebruiker die het tabblad sluit op een kwart van het bestand en een moment later dezelfde link weer opent

De availability-lus achter TPdfProgressiveDocument

In het PDFium Component woont de hele sessie in TPdfProgressiveDocument, een TPdf-subklasse die een PDFium-availabilityprovider in leven houdt terwijl een random-access-stream volloopt. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) neemt de onderliggende stream en de logische grootte van het externe bestand (de Content-Length, niet de huidige lengte van je lokale voorraad), knoopt een IsDataAvail-callback en een AddSegment-callback aan en roept FPDFAvail_Create aan. Zodra OpenProgressiveDocument slaagt, gedraagt het object zich als elke andere actieve TPdf: pagina's, tekst, rendering en opslaan werken allemaal via de gewone members

Elke parseerstap is een vraag aan jouw code. Als PDFium een bereik wil, antwoordt het component ja als het bereik binnen de aaneengesloten prefix ligt die AvailableByteCount beschrijft, of binnen een bereik dat al via de RangeRequests-scheduler is voltooid. Een OnDataAvailable-handler krijgt dan het laatste woord, en zo kan een sparse cache antwoorden voor bereiken waar geen van beide iets over zegt. CheckDocumentAvailability geeft één van drie TPdfDataAvailability-waarden terug (pdaAvailable, pdaNotAvailable, pdaError) en overhandigt de bytebereiken die PDFium vroeg als een gesorteerde, samengevoegde TPdfDownloadRanges-array. Die bereiken staan tegen de tijd dat je ze ziet al in de wachtrij op rrpImmediate-prioriteit, dus de hintarray is voor logging en voortgangsweergave; de werkrij is RangeRequests

// FetchRange is uw transport (HTTP Range GET, socket, blob-lezer):
// hij schrijft Size bytes op Offset in Store en geeft terug hoeveel aankwamen
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;
    // De hints staan al in de wachtrij; schrijf eerst de bytes, voltooi daarna
    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;

Twee details in die lus wegen zwaar. De rondecap bestaat omdat een dode link CheckDocumentAvailability bij elke aanroep om dezelfde bereiken laat vragen, en een eindloze lus van een netwerkstoring een hangende UI maakt. De volgorde telt omdat de scheduler zijn eigen toestand serialiseert met een critical section maar niets doet voor TStream.Position op de onderliggende opslag. Een transportthread moet de responsebytes in de stream schrijven voordat hij CompleteRequest aanroept, want PDFium kan het bereik lezen op het moment dat de afronding wordt gepubliceerd. Gelijktijdige schrijvers hebben gepositioneerde I/O of een eigen lock nodig

De availability-lus van TPdfProgressiveDocument in PDFium Component: BeginProgressiveLoad maakt de FPDFAvail-provider, CheckDocumentAvailability overhandigt gesorteerde samengevoegde downloadhints die met rrpImmediate-prioriteit zijn gequeud, het transport schrijft bytes in de opslag voordat CompleteRequest elk bereik aan PDFium publiceert, en de lus is gekapt op 64 rondes omdat een dode verbinding blijft vragen om dezelfde bereiken
Schrijf de bytes, voltooi dan het verzoek: op het moment dat een voltooiing wordt gepubliceerd mag PDFium dat bereik lezen, en niets bewaakt de streampositie voor u

Waarom weigert AvailableByteCount achteruit te gaan?

AvailableByteCount groeit alleen maar. Een kleinere waarde toekennen gooit een EPdfError met 'Available byte count cannot move backwards', want zodra de availabilitycallback PDFium heeft verteld dat een bereik bestaat, heeft de parser er al objecten uit kunnen lezen en cachen. Die bytes daarna weer wegnemen zou PDFium met objecten achterlaten waarvan de bron door de availability-antwoorden nu wordt ontkend. Dezelfde setter weigert waarden groter dan LogicalFileSize en gooit 'No progressive load is active' buiten een sessie

Die laatste controle bepaalt waar bytes die je al hebt thuishoren. Heeft een eerder bezoek de eerste 300 KB van het bestand in een cache achtergelaten, geef die telling dan door als AInitialAvailableByteCount; het component legt hem vast voordat FPDFAvail_Create draait, zodat PDFium bij zijn eerste blik op de header hem al ziet. Met een begintelling van nul leest Linearization plnUnknown totdat PDFium de header heeft gezien; dat is de normale begintoestand

Het verhogen van de prefix annuleert ook werk. Elke lopende aanvraag die overlapt met de pas aangekondigde bytes is nu overbodig, dus de scheduler laat hem vallen en vuurt er OnCancelRequest voor af; een late CompleteRequest voor die aanvraag geeft False terug. Een opslag die uit de volgorde vult, zou zich helemaal niet via de prefix moeten uitdrukken. Rond de bereiken af via de scheduler, of antwoord per bereik in OnDataAvailable. Een exception binnen die handler kan de C-callbackgrens niet oversteken, dus het component vangt hem op en meldt het bereik als ontbrekend, en PDFium vraagt bij de volgende controle gewoon opnieuw

Wanneer opent een gedeeltelijk gedownloade PDF werkelijk?

Alleen een gelinieariseerde PDF opent voordat het hele bestand er is. OpenProgressiveDocument bekijkt de eigenschap Linearization (plnUnknown, plnNotLinearized, plnLinearized) en kiest de lader. Een gelinieariseerd bestand opent via FPDFAvail_GetDocument zodra de first-page-sectie en de hinttabellen aanwezig zijn. Een niet-gelinieariseerd bestand gaat via FPDF_LoadCustomDocument op hetzelfde file-access-record, en voor zo'n bestand meldt PDFium het document pas als beschikbaar wanneer elke byte er is. Die routering houdt de nul-pagina-handle uit de openingsalinea uit je viewer

Hoe OpenProgressiveDocument een gedeeltelijke download in PDFium Component routeert: een gelinieariseerd bestand opent via FPDFAvail_GetDocument zodra de first-page-sectie en hinttabellen aankomen, een niet-gelinieariseerd bestand heeft FPDF_LoadCustomDocument en elke byte nodig, en LoadAvailablePage controleert form-availability met FPDFAvail_IsFormAvail vóór de paginacontrole, waarmee de niet-null-nul-pagina-handle-val wordt vermeden
Alleen gelinieariseerde bestanden krijgen een voorsprong; op al het restant kan FPDFAvail_GetDocument een open-ogend document met nul pagina's teruggeven, en precies dat voorkomt de routering

Het bestand op de server bepaalt dus hoe snel de eerste pagina verschijnt. Als tijd tot first paint telt en je de publicerkant beheerst, lineariseer de bestanden dan daar. TPdf.SaveAsLinearized schrijft de Annex F-indeling vanuit het component zelf, en de Fast Web View- en hinttabelwalkthrough behandelt wat die indeling bevat. Voor bestanden die je niet beheerst, laadt een niet-gelinieariseerde PDF nog steeds via dezelfde lus; hij bereikt pdaAvailable alleen bij 100 procent in plaats van vroeg

LoadAvailablePage neemt een paginanummer vanaf één en houdt de volgorde aan die PDFium verwacht. Vóór de eerste paginacontrole draait hij CheckFormAvailability, die FPDFAvail_IsFormAvail omwikkelt, en pas daarna roept hij FPDFAvail_IsPageAvail aan. Een uitkomst van pfaNotPresent is het gewone antwoord voor een document zonder AcroForm en blokkeert niets. Is de pagina klaar, dan maakt LoadAvailablePage hem de actieve pagina, zodat een viewer pagina 1 van een gelinieariseerde brochure kan renderen terwijl latere pagina's nog onderweg zijn. Het paginawachten heeft dezelfde vorm als de eerste listing: roep LoadAvailablePage aan, tap RangeRequests af bij pdaNotAvailable, stop bij pdaAvailable of pdaError, en houd een rondecap aan. FirstAvailablePageNumber meldt de pagina die het linearisatie-woordenboek als eerste aanwijst, al omgezet van PDFiums nulgebaseerde index. Voor een niet-gelinieariseerd bestand meldt elke pagina meteen pdaAvailable, want het document kon pas openen toen het bestand compleet was

Retries, korte reads en prioriteiten in de bereikscheduler

De FPDFAvail_*-API zelf weet niets van netwerken. Hij zegt welke bytes de parser nu nodig heeft en vraagt later opnieuw; er is geen begrip van een aanvraag, een retry of een annulering. TPdfRangeRequestScheduler levert die, en vier van zijn regels bepalen hoe je het transport schrijft

  • Een korte response geldt als voortgang. CompleteRequest(Request, BytesReceived) met minder bytes dan gevraagd publiceert de prefix en zet de rest in de wachtrij. De korte response telt ook als mislukte poging, dus de rest blijft gebonden aan MaxRetryCount en wordt opgegeven zodra die op is; nul bytes is een gewone mislukte poging
  • MaxRetryCount staat standaard op 2, dus één bereik krijgt in totaal drie pogingen. FailRequest geeft True terug als hij het bereik opnieuw in de wachtrij zette en False zodra het bereik is opgegeven; Statistics.AbandonedRequestCount houdt bij hoeveel er opgaven
  • MaxRequestSize splijt grote bereiken bij het uithalen in brokken, en MergeGap laat twee wachtende bereiken samensmelten over een kleine onbekende tussenruimte, maar nooit over bytes die al voltooid of onderweg zijn
  • Hints van CheckDocumentAvailability en LoadAvailablePage komen binnen op rrpImmediate. Formulierhints van een directe CheckFormAvailability-aanroep komen binnen op rrpNormal; draait LoadAvailablePage die controle zelf en ontbreekt de formulierdata, dan worden de hints op rrpImmediate gezet. TryDequeue bedient altijd eerst de hoogste prioriteit en binnen een prioriteit de laagste offset

De prioriteitsregel betaalt zich terug bij prefetchen. Zet het hele bestand op rrpBackground direct nadat het document opent, en de scheduler trekt alles wat al voltooid of onderweg is eraf, zodat alleen de ontbrekende bytes de draad op gaan. Springt de gebruiker dan naar pagina 40 en overlapt de hint van die pagina een achtergrondbrok die al aan het downloaden is, dan trekt de scheduler de achtergrondaanvraag terug, vuurt er OnCancelRequest voor af, zet de niet-overlappende staarten terug op achtergrondprioriteit zonder ze een retry aan te rekenen, en zet de overlap in de wachtrij als vers onmiddellijk werk. De sprong wint de verbinding. Zonder dat zou de pagina-aanvraag achter een brok van 256 KB wachten waar hij niets mee heeft

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // de brokgrootte kies je zelf
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// Aangeroepen op een werkthread als één HTTP Range-response klaar is.
// WriteAt is je eigen gepositioneerde schrijfactie naar de onderliggende opslag
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);              // eerst de bytes
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // opgegeven, of uit een geannuleerde sessie
end;

Zowel CompleteRequest als FailRequest is veilig aan te roepen vanuit de werkthread; de scheduler pakt zijn eigen lock. Een aanvraag die is verdrongen of bij een geannuleerde sessie hoort, komt terug als False zonder iets aan te raken, dus de worker hoeft niet te weten waarom zijn bereik verouderd raakte

Wat geeft CancelProgressiveLoad vrij, en in welke volgorde?

CancelProgressiveLoad sloopt een sessie in vier stappen af, altijd in dezelfde volgorde: annuleer de bereikscheduler, sluit het document, vernietig de availabilityhandle met FPDFAvail_Destroy en geef daarna de callbackrecords en de streamadapter vrij. De scheduler eerst annuleren schuift zijn generatieteller op, laat elke wachtende en lopende aanvraag vallen en vuurt voor elke lopende OnCancelRequest af. Een transportafronding die daarna binnenkomt, draagt de oude generatie, en CompleteRequest geeft False terug. Het document sluit vóór de availabilityhandle en de streamadapter verdwijnen, omdat PDFium via de file-access-provider kan blijven lezen terwijl het een document sluit

De vaste sloopvolgorde van CancelProgressiveLoad in PDFium Component: annuleer eerst de range-scheduler zodat late voltooiingen op de verhoogde generatieteller stuiten en False teruggeven, sluit het document voordat de file-access-adapter verdwijnt, vernietig de availability-handle met FPDFAvail_Destroy, en geef pas daarna de callback-records prijs en maak de streamadapter vrij
Één idempotente methode ruimt een mislukte start, een gebruikersannulering en de destructor op dezelfde manier op; met een workerthread die in de opslag schrijft blijft de streameigendom bij u
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // De scheduler leeft zo lang als FPdf, dus sluit hem een keer aan
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // uw code: sluit die socket of dat verzoek
end;

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

De methode is idempotent en dient als de enige opruimweg voor drie situaties: een BeginProgressiveLoad die halverwege de bouw faalt, een uitdrukkelijke annulering door de gebruiker en de destructor. BeginProgressiveLoad roept hem ook aan, dus hetzelfde object herstarten op een nieuwe URL is prima zolang de eerdere sessie het openen nooit haalde. Zodra OpenProgressiveDocument is geslaagd, is het object actief, en gooit BeginProgressiveLoad de gebruikelijke fout 'Cannot perform this operation on an active'; roep eerst CancelProgressiveLoad aan. OnCancelRequest is ook de enige plek waar jouw sockets worden gesloten, want de scheduler heeft geen begrip van een socket. Exceptions daarin worden per aanvraag ingeslikt, dus één afbreking die faalt, kan de rest niet blokkeren

Wie de opslag schrijft, bepaalt wie hem bezit. Schrijft een werkthread in de onderliggende stream, geef dan AOwnsStream = False door en geef de stream zelf vrij nadat de worker is gestopt. Het eigendom overdragen betekent dat de annulering de stream vrijgeeft terwijl een schrijfactie die al bezig is, nog onderweg kan zijn. Houd het eigendom vast zodra een andere thread dan de aanroeper de opslag aanraakt; AOwnsStream = True past alleen bij een volledig synchroon transport zoals de eerste listing

Features die op het hele bestand wachten

Sommige features hebben de originele bestandsbytes nodig, niet het geparsde document, en ze weigeren een onvolledige progressieve bron ronduit. ReadXmpPacket gooit 'PDF/A metadata is unavailable until progressive loading completes'. ValidatePades geeft een resultaat waarvan SourceStatus gelijk is aan pvssIncomplete, en ValidatePdfMac meldt niet-ondersteund met een melding die om de complete bron vraagt. BeginIncrementalSave faalt ook, want een incrementele update moet vastlopen op exact de bytes die waren geladen

De volledigheidstest achter allemaal is AvailableByteCount dat LogicalFileSize bereikt. Een transport dat alles via de scheduler aanlevert, kan dus elke byte vasthouden en toch horen dat de bron onvolledig is, omdat de aaneengesloten prefix nooit bewoog. Publiceer de prefix zodra de scheduler volledige dekking bevestigt:

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);   // je eigen UI
end;

Eën formaatgrens geldt voordat dit allemaal begint. Op Windows bewaart FPDF_FILEACCESS de bestandslengte in een 32-bit veld, dus BeginProgressiveLoad weigert een logische grootte boven 4 GiB met een EPdfError in plaats van PDFium een afgeknipte lengte te laten parsen

Voor het op aanvraag laden van een compleet lokaal bestand via een streamadapter, zie grote PDF's op aanvraag streamen met PDFium; voor een PDF die in een grotere buffer zit, zie byte range loading voor ingebedde PDF's. Een trage render van een pagina die al binnen is, stoppen is een ander mechanisme, behandeld in annuleerbare progressieve paginarendering. TPdfProgressiveDocument, zijn bereikscheduler en SaveAsLinearized maken deel uit van het PDFium Component for Delphi en C++Builder