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 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 tableurafData→/Data: des données lisibles par machine dont le contenu visible dérive ou qu'il représenteafAlternative→/Alternative,afSupplement→/Supplement,afUnspecified→/UnspecifiedafEncryptedPayload,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
// 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
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