Article technique

Téléchargement progressif et annulation PDFium en Delphi

Un handle de document non nul avec un compte de pages de zéro, c'est ce que FPDFAvail_GetDocument peut rendre quand on l'appelle sur un PDF qui n'a jamais été linéarisé, même après que FPDFAvail_IsDocAvail a rapporté PDF_DATA_AVAIL. Le handle a l'air ouvert, rien ne se plaint, et le viewer montre un document vide. L'API de disponibilité de PDFium lit la disposition linéarisée de l'annexe F d'ISO 32000-1 ; tout autre fichier doit être complet et s'ouvrir par le chemin ordinaire de document personnalisé. Cette décision de routage fait la moitié de ce qu'implique l'ouverture d'un PDF pendant le téléchargement. L'autre moitié, c'est l'utilisateur qui ferme l'onglet au quart du fichier et rouvre le même lien un instant plus tard

La boucle de disponibilité derrière TPdfProgressiveDocument

Dans le PDFium Component, toute la session vit dans TPdfProgressiveDocument, une sous-classe de TPdf qui garde un fournisseur de disponibilité PDFium en vie pendant qu'un flux à accès aléatoire se remplit. BeginProgressiveLoad(AStream, AFileSize, AOwnsStream, AInitialAvailableByteCount) prend le flux sous-jacent et la taille logique du fichier distant (le Content-Length, pas la longueur actuelle de votre magasin local), branche un callback IsDataAvail et un callback AddSegment, et appelle FPDFAvail_Create. Une fois que OpenProgressiveDocument réussit, l'objet se comporte comme n'importe quel TPdf actif : pages, texte, rendu et sauvegarde passent tous par les membres habituels

Chaque étape d'analyse est une question posée à votre code. Quand PDFium veut une plage, le composant répond oui si la plage se trouve dans le préfixe contigu décrit par AvailableByteCount, ou dans une plage déjà complétée par l'ordonnanceur RangeRequests. Un handler OnDataAvailable a alors le dernier mot, c'est ainsi qu'un cache creux répond pour des plages que ni l'un ni l'autre ne peuvent décrire. CheckDocumentAvailability renvoie l'une des trois valeurs TPdfDataAvailability (pdaAvailable, pdaNotAvailable, pdaError) et remet les plages d'octets demandées par PDFium sous forme de tableau TPdfDownloadRanges trié et fusionné. Ces plages sont déjà mises en file sur l'ordonnanceur à priorité rrpImmediate au moment où vous les voyez, donc le tableau d'indications sert à la journalisation et à l'affichage de progression ; la file de travail, c'est RangeRequests

// FetchRange est votre transport (HTTP Range GET, socket, lecteur de blob) :
// il écrit Size octets à Offset dans Store et renvoie combien sont arrivés
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;
    // Les indications sont déjà en file ; écrivez d'abord les octets, puis complétez
    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;

Deux détails de cette boucle portent du poids. Le plafond de tours existe parce qu'un lien mort fait demander à CheckDocumentAvailability les mêmes plages à chaque appel, et une boucle sans borne transforme une panne réseau en UI figée. L'ordre compte parce que l'ordonnanceur sérialise son propre état avec une section critique mais ne fait rien pour TStream.Position sur le magasin sous-jacent. Un thread de transport doit écrire les octets de réponse dans le flux avant d'appeler CompleteRequest, car PDFium peut lire la plage dès que la complétion est publiée. Des écrivains concurrents ont besoin d'E/S positionnées ou d'un verrou à eux

La boucle de disponibilité de TPdfProgressiveDocument dans PDFium Component : BeginProgressiveLoad crée le fournisseur FPDFAvail, CheckDocumentAvailability rend des indications de téléchargement triées et fusionnées mises en file à la priorité rrpImmediate, le transport écrit les octets dans le magasin avant que CompleteRequest ne publie chaque plage à PDFium, et la boucle est plafonnée à 64 tours parce qu'un lien mort redemande sans fin les mêmes plages
Écrivez les octets, puis complétez la requête : dès qu'une complétion est publiée, PDFium peut lire cette plage, et rien ne protège la position du flux à votre place

Pourquoi AvailableByteCount refuse-t-il de reculer ?

AvailableByteCount ne fait que grossir. Affecter une valeur plus petite lève EPdfError avec « Available byte count cannot move backwards », car une fois que le callback de disponibilité a dit à PDFium qu'une plage existe, l'analyseur a peut-être déjà lu et mis en cache des objets dedans. Retirer ces octets ensuite laisserait PDFium détenir des objets dont la source est niée par les réponses de disponibilité. Le même setter rejette les valeurs plus grandes que LogicalFileSize et lève « No progressive load is active » hors session

Ce dernier contrôle décide où appartiennent les octets que vous détenez déjà. Si une visite précédente a laissé les 300 premiers Ko du fichier dans un cache, passez ce compte comme AInitialAvailableByteCount ; le composant l'enregistre avant que FPDFAvail_Create ne tourne, donc le premier coup d'œil de PDFium à l'en-tête le voit déjà. Avec un compte initial de zéro, Linearization se lit plnUnknown tant que PDFium n'a pas vu l'en-tête ; c'est l'état de départ normal

Monter le préfixe annule aussi du travail. Toute requête en vol qui chevauche les octets nouvellement annoncés devient redondante, donc l'ordonnanceur la jette et déclenche OnCancelRequest pour elle ; un CompleteRequest tardif pour cette requête renvoie False. Un magasin qui se remplit dans le désordre ne devrait pas essayer de s'exprimer par le préfixe du tout. Complétez les plages par l'ordonnanceur, ou répondez par plage dans OnDataAvailable. Une exception levée à l'intérieur de ce handler ne peut pas traverser la frontière du callback C, donc le composant l'attrape et rapporte la plage comme manquante, et PDFium redemande simplement au prochain contrôle

Quand un PDF partiellement téléchargé peut-il réellement s'ouvrir ?

Seul un PDF linéarisé s'ouvre avant l'arrivée du fichier entier. OpenProgressiveDocument consulte la propriété Linearization (plnUnknown, plnNotLinearized, plnLinearized) et choisit le chargeur. Un fichier linéarisé s'ouvre via FPDFAvail_GetDocument dès que la section première page et les tables d'indications sont présentes. Un fichier non linéarisé passe par FPDF_LoadCustomDocument sur le même enregistrement d'accès fichier, et pour un tel fichier PDFium ne déclare le document disponible qu'une fois chaque octet là. Ce routage est ce qui garde le handle à zéro page du paragraphe d'ouverture hors de votre viewer

Comment OpenProgressiveDocument route un téléchargement partiel dans PDFium Component : un fichier linéarisé s'ouvre via FPDFAvail_GetDocument dès que la section de première page et les tables d'indications arrivent, un fichier non linéarisé a besoin de FPDF_LoadCustomDocument et de chaque octet, et LoadAvailablePage vérifie la disponibilité du formulaire avec FPDFAvail_IsFormAvail avant le contrôle de page, évitant le piège du handle non nul à zéro page
Seuls les fichiers linéarisés gagnent une longueur d'avance ; sur tout le reste, FPDFAvail_GetDocument peut renvoyer un document qui semble ouvert avec zéro page, et c'est exactement ce que le routage empêche

Le fichier sur le serveur décide donc de la vitesse d'apparition de la première page. Si le délai jusqu'au premier rendu compte et que vous contrôlez le côté publication, linéarisez les fichiers là-bas. TPdf.SaveAsLinearized écrit la disposition de l'annexe F depuis le composant lui-même, et la démonstration Fast Web View et tables d'indications couvre ce que contient cette disposition. Pour les fichiers que vous ne contrôlez pas, un PDF non linéarisé se charge quand même par la même boucle ; il atteint juste pdaAvailable à 100 pour cent au lieu de tôt

LoadAvailablePage prend un numéro de page à base 1 et garde l'ordre qu'attend PDFium. Avant le contrôle de première page, il exécute CheckFormAvailability, qui enrobe FPDFAvail_IsFormAvail, et seulement ensuite appelle FPDFAvail_IsPageAvail. Un résultat pfaNotPresent est la réponse normale pour un document sans AcroForm et ne bloque rien. Quand la page est prête, LoadAvailablePage la rend page active, donc un viewer peut rendre la page 1 d'une brochure linéarisée pendant que les pages suivantes sont encore en transit. L'attente de page a la même forme que le premier listing : appelez LoadAvailablePage, drainez RangeRequests sur pdaNotAvailable, arrêtez-vous sur pdaAvailable ou pdaError, et gardez un plafond de tours. FirstAvailablePageNumber rapporte la page que le dictionnaire de linéarisation désigne comme première, déjà convertie depuis l'index à base zéro de PDFium. Pour un fichier non linéarisé, chaque page rapporte pdaAvailable aussitôt, car le document ne pouvait s'ouvrir qu'une fois le fichier complet

Réessais, lectures courtes et priorités dans l'ordonnanceur de plages

L'API FPDFAvail_* elle-même ne sait rien des réseaux. Elle dit quels octets l'analyseur exige à l'instant et redemande plus tard ; il n'y a aucune notion de requête, de réessai ni d'annulation. TPdfRangeRequestScheduler fournit ça, et quatre de ses règles façonnent la façon d'écrire le transport

  • Une réponse courte est traitée comme une progression. CompleteRequest(Request, BytesReceived) avec moins d'octets que demandé publie le préfixe et remet le reste en file. La réponse courte compte aussi comme une tentative ratée, donc le reste reste lié par MaxRetryCount et est abandonné une fois ce compteur épuisé ; zéro octet est une simple tentative ratée
  • MaxRetryCount vaut 2 par défaut, donc une plage obtient trois tentatives au total. FailRequest renvoie True quand il a remis la plage en file et False une fois la plage abandonnée ; Statistics.AbandonedRequestCount suit combien ont renoncé
  • MaxRequestSize scinde les grandes plages en morceaux au moment du dequeue, et MergeGap laisse deux plages en attente fusionner par-delà un petit trou inconnu, mais jamais par-delà des octets déjà complétés ou en vol
  • Les indications de CheckDocumentAvailability et LoadAvailablePage arrivent à rrpImmediate. Les indications de formulaire d'un appel direct à CheckFormAvailability arrivent à rrpNormal ; quand LoadAvailablePage exécute ce contrôle lui-même et que les données de formulaire manquent, les indications sont mises en file à rrpImmediate. TryDequeue sert toujours la priorité la plus haute d'abord et le décalage le plus bas dans une priorité

La règle de priorité se paie quand vous préchargez. Mettez le fichier entier en file à rrpBackground aussitôt après l'ouverture du document, et l'ordonnanceur retranche tout ce qui est déjà complété ou en vol, donc seuls les octets manquants partent sur le fil. Quand l'utilisateur saute ensuite à la page 40 et que l'indication de cette page chevauche un morceau d'arrière-plan déjà en téléchargement, l'ordonnanceur retire la requête d'arrière-plan, déclenche OnCancelRequest pour elle, remet les queues non chevauchées à priorité arrière-plan sans leur charger de réessai, et met le chevauchement en file comme travail immédiat frais. Le saut gagne la connexion. Sans ça, la requête de page attendrait derrière un morceau de 256 Ko qui ne l'intéresse pas

procedure TDownloadForm.QueueRestOfFile;
var
  Whole: TPdfDownloadRanges;
begin
  FPdf.RangeRequests.MaxRequestSize := 256 * 1024;  // la taille de morceau est votre choix
  SetLength(Whole, 1);
  Whole[0].Offset := 0;
  Whole[0].Size := FPdf.LogicalFileSize;
  FPdf.RangeRequests.EnqueueHints(Whole, rrpBackground);
end;

// Appelé sur un thread de travail quand une réponse HTTP Range se termine.
// WriteAt est votre propre écriture positionnée dans le magasin sous-jacent
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);              // les octets d'abord
    FPdf.RangeRequests.CompleteRequest(Request, Length(Body));
  end
  else if not FPdf.RangeRequests.FailRequest(Request) then
    TThread.Queue(nil, ShowRangeGaveUp);  // abandonnée, ou d'une session annulée
end;

CompleteRequest et FailRequest se appellent sans danger depuis le thread de travail ; l'ordonnanceur prend son propre verrou. Une requête qui a été supplantée ou appartient à une session annulée revient en False sans rien toucher, donc le worker n'a pas besoin de savoir pourquoi sa plage est devenue périmée

Que libère CancelProgressiveLoad, et dans quel ordre ?

CancelProgressiveLoad démonte une session en quatre étapes, toujours dans le même ordre : annulez l'ordonnanceur de plages, fermez le document, détruisez le handle de disponibilité avec FPDFAvail_Destroy, puis libérez les enregistrements de callbacks et l'adaptateur de flux. Annuler l'ordonnanceur d'abord avance son compteur de génération, jette toute requête en attente et en vol, et déclenche OnCancelRequest pour chacune de celles en vol. Une complétion de transport qui atterrit ensuite porte l'ancienne génération, et CompleteRequest renvoie False. Le document se ferme avant que le handle de disponibilité et l'adaptateur de flux ne disparaissent parce que PDFium peut encore lire à travers le fournisseur d'accès fichier pendant qu'il ferme un document

L'ordre de démontage fixe de CancelProgressiveLoad dans PDFium Component : annulez d'abord l'ordonnanceur de plages pour que les complétions tardives butent sur le compteur de génération incrémenté et renvoient False, fermez le document avant que l'adaptateur d'accès fichier ne disparaisse, détruisez le handle de disponibilité avec FPDFAvail_Destroy, et seulement ensuite disposez les enregistrements de callbacks et libérez l'adaptateur de flux
Une méthode idempotente nettoie aussi bien un démarrage raté, une annulation utilisateur que le destructeur ; avec un thread de travail qui écrit dans le magasin, la propriété du flux reste à vous
procedure TDownloadForm.FormCreate(Sender: TObject);
begin
  FPdf := TPdfProgressiveDocument.Create(nil);
  // L'ordonnanceur vit autant que FPdf, donc câblez-le une fois
  FPdf.RangeRequests.OnCancelRequest := RangeCancelled;
end;

procedure TDownloadForm.RangeCancelled(Sender: TObject; RequestId: UInt64;
  Attempt: Cardinal);
begin
  FTransport.Abort(RequestId);   // votre code : fermez ce socket ou cette requête
end;

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

La méthode est idempotente et sert d'unique chemin de nettoyage pour trois situations : un BeginProgressiveLoad qui échoue à mi-construction, une annulation explicite de l'utilisateur, et le destructeur. BeginProgressiveLoad l'appelle aussi, donc redémarrer le même objet sur une nouvelle URL passe tant que la session antérieure n'est jamais allée jusqu'à l'ouverture. Une fois que OpenProgressiveDocument a réussi, l'objet est actif, et BeginProgressiveLoad lève l'erreur habituelle « Cannot perform this operation on an active » ; appelez d'abord CancelProgressiveLoad. OnCancelRequest est aussi le seul endroit où vos sockets se ferment, puisque l'ordonnanceur ne sait pas ce qu'est un socket. Les exceptions levées à l'intérieur sont avalées par requête, donc un abandon en échec ne peut pas bloquer les autres

Qui écrit le magasin décide qui le possède. Avec un thread de travail écrivant dans le flux sous-jacent, passez AOwnsStream = False et libérez le flux vous-même après l'arrêt du worker. Confier la possession veut dire que l'annulation libère le flux alors qu'un écrit déjà en cours est peut-être encore en route. Gardez la possession chaque fois qu'un thread autre que l'appelant touche au magasin ; AOwnsStream = True ne convient qu'à un transport entièrement synchrone comme le premier listing

Les fonctions qui attendent le fichier entier

Certaines fonctions exigent les octets du fichier d'origine, pas le document analysé, et elles refusent carrément une source progressive incomplète. ReadXmpPacket lève « PDF/A metadata is unavailable until progressive loading completes ». ValidatePades renvoie un résultat dont SourceStatus vaut pvssIncomplete, et ValidatePdfMac rapporte non supporté avec un message réclamant la source complète. BeginIncrementalSave échoue aussi, car une mise à jour incrémentale doit s'ajouter aux octets exacts qui ont été chargés

Le test de complétude derrière tout ça est AvailableByteCount atteignant LogicalFileSize. Un transport qui livre tout par l'ordonnanceur peut donc détenir chaque octet et se faire dire quand même que la source est incomplète, parce que le préfixe contigu n'a jamais bougé. Publiez le préfixe une fois que l'ordonnanceur confirme la couverture complète :

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

Une limite de taille s'applique avant tout ça. Sur Windows, FPDF_FILEACCESS stocke la longueur du fichier dans un champ 32 bits, donc BeginProgressiveLoad rejette une taille logique au-dessus de 4 Gio avec un EPdfError au lieu de laisser PDFium analyser une longueur tronquée

Pour charger un fichier local complet à la demande via un adaptateur de flux, voir le streaming de grands PDF à la demande avec PDFium ; pour un PDF qui se trouve dans un tampon plus grand, voir le chargement par plages d'octets pour les PDF embarqués. Arrêter un rendu lent d'une page déjà arrivée est un autre mécanisme, couvert dans le rendu progressif de pages annulable. TPdfProgressiveDocument, son ordonnanceur de plages et SaveAsLinearized font partie du PDFium Component pour Delphi et C++Builder