Article technique

Fichiers associés PDF/A-3 et AFRelationship en Delphi

Pour joindre un fichier source à un document PDF/A-3 depuis Delphi, PDFium Component écrit une chaîne de fichiers associés PDF 2.0 : un flux de fichier embarqué avec un /Subtype MIME, une spécification de fichier portant /AFRelationship, et un tableau /AF accroché au catalogue ou à une page. InjectAssociateFiles et TPdf.SaveAsWithAssociateFiles construisent cette chaîne en une seule mise à jour incrémentale, avec le type MIME sérialisé comme un unique nom PDF correctement échappé. Le reste de ce billet couvre ce qu'un validateur contrôle, le piège d'un seul caractère qui casse text/plain, et les contrôles qui empêchent une coquille ou un trailer illisible de produire le mauvais fichier

Que faut-il réellement à un fichier associé PDF/A-3 ?

Une pièce jointe PDF/A-3 passe la validation seulement quand trois objets se donnent raison : le flux de fichier embarqué déclare /Type /EmbeddedFile plus un /Subtype MIME, le dictionnaire de spécification de fichier (ISO 32000-2 §7.11.3) porte /F, /UF, /EF et /AFRelationship, et quelque chose dans le document référence cette spécification de fichier via un tableau /AF (ISO 32000-2 §14.13). L'embarquement simple par l'arbre /Names /EmbeddedFiles, que fait TPdf.CreateAttachment, ne pose aucun des champs d'association. Un passage de validation PDF/A-3b rend la dépendance concrète : ne renommez que la clé /AFRelationship et le fichier échoue sur exactement une règle de la clause 6.8 d'ISO 19005-3 ; ne retirez que le /Subtype MIME et une autre règle 6.8 échoue ; mettez la même pièce jointe dans un candidat PDF/A-1b et elle est rejetée carrément, car PDF/A-1 interdit les fichiers embarqués peu importe la propreté des métadonnées

La chaîne de trois objets d'un fichier associé PDF A-3 dans PDFium Component : un flux EmbeddedFile avec un Subtype MIME tel que application xml, une spécification de fichier avec F, UF, EF et AFRelationship réglé à Data, et un tableau AF pour elle depuis le catalogue ou une page, les trois objets qu'un validateur contrôle avant que la clause 6.8 d'ISO 19005-3 ne passe
Flux, spécification de fichier et tableau AF doivent se donner raison ; l'embarquement simple par arbre de noms de TPdf.CreateAttachment ne pose aucun des champs d'association, par conception

La valeur de relation est la partie que les gens ont tendance à deviner. TPdfAFRelationship dans FPdfAssocFiles mappe un membre d'énumération vers chaque jeton de nom que l'injecteur peut émettre, et seuls les cinq premiers appartiennent au sous-ensemble qu'ISO 19005-3 reconnaît :

  • afSource → /Source : l'original dont le PDF a été produit, comme un fichier de traitement de texte ou un tableur
  • afData → /Data : des données lisibles par machine dont le contenu visible dérive ou qu'il représente
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, afFormData, afTemplate : des ajouts PDF 2.0 qui tombent hors du sous-ensemble PDF/A-3, donc tenez-les hors des sorties d'archivage

Pourquoi /Subtype /text/plain casse-t-il la validation ?

C'est une erreur de tokenisation, pas un manque de conformité. Concaténez la chaîne de l'appelant juste après une barre oblique et vous obtenez /Subtype /text/plain. En syntaxe PDF, la seconde barre oblique démarre un nouvel objet nom (ISO 32000-1 §7.3.5), si bien que le dictionnaire du flux tient soudain la clé /Subtype, le nom /text, et un nom superflu /plain qui déséquilibre les paires clé-valeur. Un validateur PDF/A indépendant rejette un tel fichier en analysant le dictionnaire EmbeddedFile, avant d'atteindre la moindre règle PDF/A, voilà pourquoi l'échec ressemble à une corruption de fichier plutôt qu'à une propriété de pièce jointe manquante

PDFium Component route la valeur MIME par EscapePdfName, qui émet /text#2Fplain : un seul nom dont la valeur décodée est text/plain. L'échappement est délibérément plus large que la barre oblique. Chaque octet à 32 ou en dessous (espace, tabulation, CR, LF), chaque octet à 127 ou au-dessus, les délimiteurs ()<>[]{}/% et le caractère d'échappement # lui-même deviennent #XX. N'échapper que la barre oblique laisserait un autre trou : une chaîne MIME contenant >> ou de l'espace blanc pourrait fermer le dictionnaire trop tôt ou injecter des clés supplémentaires

Pourquoi le sous-type MIME text barre oblique plain casse l'analyse PDF A-3 dans PDFium Component : concaténer la valeur après une barre oblique produit deux objets nom, /text comme valeur plus un /plain superflu qui déséquilibre le dictionnaire EmbeddedFile, tandis qu'EscapePdfName écrit /text#2Fplain comme un seul nom qui se décode en text/plain
L'échec ressemblait à une corruption de fichier parce qu'il arrivait au parseur, avant toute règle PDF/A ; le nom échappé garde les paires équilibrées et le validateur en lecture
// MIMEType = 'text/plain'
//   concaténation naïve :  /Type /EmbeddedFile /Subtype /text/plain     (deux noms)
//   sortie de l'injecteur :  /Type /EmbeddedFile /Subtype /text#2Fplain   (un nom)
//
// Les appelants passent toujours la valeur MIME ordinaire. Pré-échapper vous-même
// double-encode le '#', qui change 'text#2Fplain' en 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';

Construire un fichier PDF/A-3 avec InjectAssociateFiles

Pour une sortie PDF/A-3, produisez le document de base conforme avec TPdf.SaveAsPdfAToStream puis appelez InjectAssociateFiles sur ce flux ; ce pipeline en deux étapes est celui qui passe la validation PDF/A-3b. TPdf.SaveAsWithAssociateFiles est le wrapper de confort, mais il enregistre par le chemin SaveAs ordinaire avec saRemoveSecurity plutôt que par l'écrivain PDF/A, donc il n'ajoute pas l'identification XMP et l'output intent qu'exige PDF/A. Notez que les types d'enregistrements vivent dans FPdfAssocFiles et FPdfPdfa, donc les deux unités appartiennent à votre clause uses. Depuis la v3.121.3, FileName et Description ne se limitent pas à l'ASCII simple : /UF et /Desc s'écrivent comme chaînes de texte PDF, l'ASCII imprimable littéralement et tout le reste en UTF-16BE avec une marque d'ordre d'octet, tandis que le nom /F hérité reste toujours de l'ASCII imprimable portable avec tout autre caractère remplacé par _, si bien que les lecteurs qui décodent /F avec leur propre page de code montrent un souligné au lieu d'un charabia

uses
  System.SysUtils, System.Classes, System.IOUtils,
  PDFium, FPdfPdfa, FPdfAssocFiles;

procedure SaveWithSourceData(Pdf: TPdf; const XmlPath, OutPath: string);
var
  PdfAOptions: TPdfASaveOptions;
  Options: TAssocFilesOptions;
  Base: TMemoryStream;
  Output: TFileStream;
begin
  PdfAOptions := TPdfASaveOptions.Default;
  PdfAOptions.Conformance := pac3b;

  Options := TAssocFilesOptions.Default;      // TargetPage = 0 : /AF au niveau catalogue
  SetLength(Options.Files, 1);
  Options.Files[0].FileName := 'invoice-data.xml';
  Options.Files[0].Description := 'Structured invoice data';
  Options.Files[0].Content := TFile.ReadAllBytes(XmlPath);
  Options.Files[0].Relationship := afData;
  Options.Files[0].MIMEType := 'application/xml';  // écrit comme /application#2Fxml

  Base := TMemoryStream.Create;
  try
    if not Pdf.SaveAsPdfAToStream(Base, PdfAOptions) then
      raise Exception.Create('PDF/A-3 base save failed');
    Output := TFileStream.Create(OutPath, fmCreate);
    try
      InjectAssociateFiles(Base, Output, Options);  // rembobine Base ; lève EPdfAssocFilesError en cas d'échec
    finally
      Output.Free;
    end;
  finally
    Base.Free;
  end;
end;

Catalogue ou page : où atterrit le tableau /AF ?

TAssocFilesOptions.TargetPage décide du propriétaire du tableau /AF : 0 l'attache au catalogue comme association au niveau du document, et 1..N l'attache au dictionnaire de cette page, à base 1. L'injecteur ajoute tout en une seule mise à jour incrémentale dans une disposition fixe (les flux embarqués, puis les spécifications de fichiers, puis le tableau /AF, puis un catalogue ou un objet page réécrit), si bien que les objets existants gardent leurs offsets et rien n'est recompressé. Toute entrée /AF antérieure sur le dictionnaire cible est remplacée, pas fusionnée, ce qui rend un enregistrement répété idempotent mais fait aussi qu'un second appel avec une liste de fichiers différente l'emporte. TargetPage est contrôlé strictement : SaveAsWithAssociateFiles et SaveAsWithAssociateFilesToStream lèvent EPdfError quand TargetPage est hors de 0..PageCount, et InjectAssociateFiles lève EPdfAssocFilesError pour un TargetPage négatif ou ne nommant aucune page existante, en laissant le flux de destination intact, si bien qu'une coquille ne peut pas transformer en silence une association de niveau page en association de niveau document. TargetPage nomme la page à cette position dans l'ordre des pages du document. Le piège à éviter dans votre propre code est de scanner les octets enregistrés pour des dictionnaires /Type /Page dans l'ordre du fichier : une fois les pages réordonnées ou insérées, les objets page peuvent être stockés dans un autre ordre que celui d'affichage, et le fichier atterrit sur une autre page

Où atterrit le tableau AF dans PDFium Component : TargetPage zéro l'attache au catalogue, les pages 1 à N l'attachent au dictionnaire de page, et une valeur hors limites lève une exception, tandis que l'injecteur ajoute tout en une mise à jour incrémentale dans une disposition fixe qui garde les offsets existants et remplace toute entrée AF antérieure
Un TargetPage hors limites lève une exception au lieu de devenir en silence une association de niveau document, et un second appel avec une liste de fichiers différente l'emporte
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
  const CsvBytes: TBytes; const OutPath: string);
var
  Options: TAssocFilesOptions;
begin
  // Un TargetPage hors limites lève EPdfError ; vérifier d'abord laisse
  // l'erreur nommer la page
  if (PageNumber < 1) or (PageNumber > Pdf.PageCount) then
    raise EArgumentOutOfRangeException.CreateFmt('No page %d', [PageNumber]);

  Options := TAssocFilesOptions.Default;
  Options.TargetPage := PageNumber;
  SetLength(Options.Files, 1);
  Options.Files[0].FileName := 'chart-data.csv';
  Options.Files[0].Content := CsvBytes;
  Options.Files[0].Relationship := afSource;
  Options.Files[0].MIMEType := 'text/csv';

  if not Pdf.SaveAsWithAssociateFiles(OutPath, Options) then
    raise Exception.Create('Associated-file save failed');
end;

Comment relire AFRelationship de façon fiable ?

TPdf.AttachmentRelationship[Index] renvoie le nom /AFRelationship d'une pièce jointe via l'export natif FPDFAttachment_GetAFRelationship, mais une chaîne vide a deux significations possibles, donc appelez d'abord AttachmentRelationshipFeaturesAvailable. Le binding est chargé avec tolérance : quand la DLL PDFium manque de cet export, toute relation se lit vide, ce qui est indiscernable d'une spécification de fichier qui n'a simplement pas de /AFRelationship. La propriété partage aussi son index avec AttachmentCount, qui compte les entrées de l'arbre /Names /EmbeddedFiles. L'injecteur n'écrit que la chaîne /AF et n'ajoute pas d'entrée d'arbre de noms, si bien qu'un fichier attaché via InjectAssociateFiles est hors de cet index ; pour confirmer la chaîne injectée, inspectez les octets sauvegardés ou faites tourner un validateur PDF/A. Les internes de cet arbre de noms sont couverts dans travailler avec les pièces jointes PDF en Delphi avec PDFium Component

procedure ReportRelationships(const FileName: string);
var
  Pdf: TPdf;
  I: Integer;
  Rel: string;
begin
  if not AttachmentRelationshipFeaturesAvailable then
  begin
    Writeln('This PDFium build cannot report /AFRelationship');
    Exit;  // une réponse vide serait ambiguë, donc ne demandez pas
  end;

  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    for I := 0 to Pdf.AttachmentCount - 1 do
    begin
      Rel := Pdf.AttachmentRelationship[I];
      if Rel = '' then
        Rel := '(no /AFRelationship)';
      Writeln(Pdf.AttachmentName[I], ': ', Rel);
    end;
  finally
    Pdf.Free;
  end;
end;

Que ne garantit pas SaveAsWithAssociateFiles ?

TPdf.SaveAsWithAssociateFiles garantit l'enveloppe de format de fichier et que les fichiers demandés ont été injectés, pas la conformité. Quand les octets enregistrés n'ont pas de trailer lisible ou que le dictionnaire catalogue est introuvable, InjectAssociateFiles lève EPdfAssocFilesError avant d'écrire quoi que ce soit et SaveAsWithAssociateFiles renvoie False ; comme la méthode construit la sortie complète dans un save store avant d'ouvrir la cible, un enregistrement rejeté ou échoué laisse un fichier existant intact. Un tableau Files vide copie le document inchangé, par conception. Le contenu de la charge est aussi votre responsabilité : l'injecteur ne vérifie pas qu'un fichier XML est bien formé, que le type MIME correspond aux octets, ou que le document de base est PDF/A du tout. Traitez le fichier final comme non vérifié tant qu'un validateur ne l'a pas vu, la même discipline que décrit PDFium Component et la conformité d'archivage PDF/A. Si vous analysez aussi vous-même les dictionnaires entrants, les mêmes règles de noms #XX s'appliquent en sens inverse, sujet traité dans les pièges des tokens de nom à l'analyse des dictionnaires PDF

Les fichiers associés, la sortie PDF/A, les métadonnées de pièces jointes et la validation arrivent tous dans le même composant, si bien que le pipeline ci-dessus tourne sans une seconde bibliothèque PDF dans le build. La référence API, le téléchargement d'essai et les options de licence sont sur la page produit PDFium Component