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
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
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 aanMaxRetryCounten wordt opgegeven zodra die op is; nul bytes is een gewone mislukte poging MaxRetryCountstaat standaard op 2, dus één bereik krijgt in totaal drie pogingen.FailRequestgeeftTrueterug als hij het bereik opnieuw in de wachtrij zette enFalsezodra het bereik is opgegeven;Statistics.AbandonedRequestCounthoudt bij hoeveel er opgavenMaxRequestSizesplijt grote bereiken bij het uithalen in brokken, enMergeGaplaat twee wachtende bereiken samensmelten over een kleine onbekende tussenruimte, maar nooit over bytes die al voltooid of onderweg zijn- Hints van
CheckDocumentAvailabilityenLoadAvailablePagekomen binnen oprrpImmediate. Formulierhints van een directeCheckFormAvailability-aanroep komen binnen oprrpNormal; draaitLoadAvailablePagedie controle zelf en ontbreekt de formulierdata, dan worden de hints oprrpImmediategezet.TryDequeuebedient 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
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