Um aus Delphi eine Quelldatei an ein PDF/A-3-Dokument anzuhängen, schreibt PDFium Component eine PDF-2.0-Associated-File-Kette: einen Embedded-File-Stream mit MIME-/Subtype, eine Dateispezifikation mit /AFRelationship und ein /AF-Array, das am Katalog oder an einer Seite hängt. InjectAssociateFiles und TPdf.SaveAsWithAssociateFiles bauen diese Kette in einem einzigen inkrementellen Update, mit dem MIME-Typ als einzelner, korrekt escapeter PDF-Name serialisiert. Der Rest dieses Artikels behandelt, was ein Validator prüft, die Ein-Zeichen-Falle, die text/plain zerbricht, und die Prüfungen, die verhindern, dass ein Tippfehler oder ein unlesbarer Trailer die falsche Datei produziert
Was braucht eine PDF/A-3-Anhängedatei wirklich?
Eine PDF/A-3-Anhängedatei besteht die Validierung nur, wenn drei Objekte sich gegenseitig bestätigen: Der Embedded-File-Stream deklariert /Type /EmbeddedFile plus einen MIME-/Subtype, das File-Specification-Dictionary (ISO 32000-2 §7.11.3) trägt /F, /UF, /EF und /AFRelationship, und etwas im Dokument referenziert diese Dateispezifikation über ein /AF-Array (ISO 32000-2 §14.13). Pures Einbetten über den /Names /EmbeddedFiles-Baum, wie es TPdf.CreateAttachment tut, setzt die Assoziationsfelder überhaupt nicht. Ein PDF/A-3b-Validierungslauf macht die Abhängigkeit konkret: Nur den /AFRelationship-Schlüssel umbenennen, und die Datei fällt durch genau eine Regel in Clause 6.8 von ISO 19005-3; nur den MIME-/Subtype weglassen, und eine andere 6.8-Regel fällt; dieselbe Anhängung in einen PDF/A-1b-Kandidaten stecken, und sie wird rundheraus abgelehnt, denn PDF/A-1 verbietet Embedded Files, egal wie ordentlich die Metadaten sind
Der Relationship-Wert ist der Teil, bei dem Leute gern raten. TPdfAFRelationship in FPdfAssocFiles mappt ein Enum-Mitglied auf jeden Namens-Token, die der Injector emittieren kann, und nur die ersten fünf gehören zur Teilmenge, die ISO 19005-3 anerkennt:
afSource→/Source: das Original, aus dem das PDF erzeugt wurde, etwa eine Textverarbeitungsdatei oder ein SpreadsheetafData→/Data: maschinenlesbare Daten, aus denen der sichtbare Inhalt abgeleitet wurde oder die er repräsentiertafAlternative→/Alternative,afSupplement→/Supplement,afUnspecified→/UnspecifiedafEncryptedPayload,afFormData,afTemplate: PDF-2.0-Ergänzungen, die außerhalb der PDF/A-3-Teilmenge liegen, also aus Archivausgaben heraushalten
Warum bricht /Subtype /text/plain die Validierung?
Es ist ein Tokenisierungsfehler, keine Compliance-Lücke. Den String des Aufrufers direkt hinter einen Slash zu konkatenieren ergibt /Subtype /text/plain. In der PDF-Syntax startet der zweite Slash ein neues Name-Objekt (ISO 32000-1 §7.3.5), das Stream-Dictionary hält also plötzlich den Schlüssel /Subtype, den Namen /text und einen herrenlosen Extra-Namen /plain, der die Key-Value-Paare aus dem Gleichgewicht bringt. Ein unabhängiger PDF/A-Validator weist so eine Datei ab, während er das EmbeddedFile-Dictionary parst, bevor er überhaupt zu einer PDF/A-Regel kommt – deshalb sieht der Fehler nach Dateikorruption aus und nicht nach einer fehlenden Attachment-Eigenschaft
PDFium Component schickt den MIME-Wert durch EscapePdfName, das /text#2Fplain emittiert: ein Name, dessen dekodierter Wert text/plain ist. Das Escaping ist bewusst breiter als der Slash. Jedes Byte von 32 abwärts (Leerzeichen, Tab, CR, LF), jedes Byte ab 127 aufwärts, die Delimiter ()<>[]{}/% und das #-Escape-Zeichen selbst werden zu #XX. Nur den Slash zu escapen hätte ein anderes Loch offengelassen: Ein MIME-String mit >> oder Whitespace könnte das Dictionary vorzeitig schließen oder Extra-Keys einschleusen
// MIMEType = 'text/plain'
// naive Konkatenation: /Type /EmbeddedFile /Subtype /text/plain (zwei Namen)
// Injector-Ausgabe: /Type /EmbeddedFile /Subtype /text#2Fplain (ein Name)
//
// Aufrufer übergeben stets den gewöhnlichen MIME-Wert. Ihn selbst vorab
// zu escapen kodiert das '#' doppelt, aus 'text#2Fplain' wird 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';
Eine PDF/A-3-Datei mit InjectAssociateFiles bauen
Erzeugen Sie für PDF/A-3-Ausgaben das konforme Basisdokument mit TPdf.SaveAsPdfAToStream und rufen Sie dann InjectAssociateFiles auf diesem Stream auf; diese Zwei-Schritte-Pipeline ist die, die die PDF/A-3b-Validierung besteht. TPdf.SaveAsWithAssociateFiles ist der Komfort-Wrapper, aber er speichert über den gewöhnlichen SaveAs-Pfad mit saRemoveSecurity statt über den PDF/A-Writer, fügt also weder die XMP-Identifikation noch den Output Intent hinzu, die PDF/A verlangt. Beachten Sie, dass die Record-Typen in FPdfAssocFiles und FPdfPdfa wohnen, also gehören beide Units in Ihre uses-Klausel. Seit v3.121.3 sind FileName und Description nicht auf pures ASCII beschränkt: /UF und /Desc werden als PDF-Text-Strings geschrieben, druckbares ASCII wörtlich und alles andere als UTF-16BE mit Byte-Order-Mark, während der Legacy-/F-Name stets portables druckbares ASCII ist, bei dem jedes andere Zeichen durch _ ersetzt wird – Reader, die /F mit ihrer eigenen Codepage dekodieren, zeigen also einen Unterstrich statt Mojibake
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 auf Katalog-Ebene
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'; // wird als /application#2Fxml geschrieben
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); // spult Base zurück; wirft EPdfAssocFilesError bei Fehlschlag
finally
Output.Free;
end;
finally
Base.Free;
end;
end;
Katalog oder Seite: Wo landet das /AF-Array?
TAssocFilesOptions.TargetPage entscheidet über den Besitzer des /AF-Arrays: 0 hängt es an den Katalog als Dokument-Level-Assoziation, und 1..N an das jeweilige Seiten-Dictionary, 1-basiert. Der Injector hängt alles als ein einziges inkrementelles Update in festem Layout an (zuerst die Embedded-Streams, dann die Dateispezifikationen, dann das /AF-Array, dann ein neu geschriebenes Katalog- oder Seiten-Objekt), also behalten existierende Objekte ihre Offsets, und nichts wird neu komprimiert. Ein früherer /AF-Eintrag am Ziel-Dictionary wird ersetzt, nicht verschmolzen – das macht ein wiederholtes Speichern idempotent, bedeutet aber auch, dass ein zweiter Aufruf mit anderer Dateiliste gewinnt. TargetPage wird streng geprüft: SaveAsWithAssociateFiles und SaveAsWithAssociateFilesToStream werfen ein EPdfError, wenn TargetPage außerhalb 0..PageCount liegt, und InjectAssociateFiles wirft ein EPdfAssocFilesError für ein negatives TargetPage oder eines, das keine existierende Seite benennt, und lässt den Ziel-Stream unverändert, ein Tippfehler kann also nicht still eine Seiten-Level-Assoziation in eine Dokument-Level-Assoziation verwandeln. TargetPage benennt die Seite an dieser Position in der Dokument-Seitenreihenfolge. Die Falle, die es im eigenen Code zu vermeiden gilt, ist, die gespeicherten Bytes nach /Type /Page-Dictionaries in Dateireihenfolge abzusuchen: Sobald Seiten umgeordnet oder eingefügt wurden, können Seiten-Objekte in einer anderen Reihenfolge gespeichert sein als angezeigt, und die Datei landet auf einer anderen Seite
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
const CsvBytes: TBytes; const OutPath: string);
var
Options: TAssocFilesOptions;
begin
// Ein TargetPage außerhalb des Bereichs wirft EPdfError; vorher zu prüfen
// lässt den Fehler die Seite benennen
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;
Wie lesen Sie AFRelationship zuverlässig zurück?
TPdf.AttachmentRelationship[Index] liefert den /AFRelationship-Namen einer Anhängung über den nativen Export FPDFAttachment_GetAFRelationship, aber ein leerer String hat zwei mögliche Bedeutungen, also rufen Sie zuerst AttachmentRelationshipFeaturesAvailable auf. Die Bindung wird tolerant geladen: Fehlt der DLL dieser Export, liest sich jede Relationship als leer, was von einer Dateispezifikation ohne /AFRelationship nicht zu unterscheiden ist. Die Property teilt sich ihren Index mit AttachmentCount, das die Einträge im /Names /EmbeddedFiles-Baum zählt. Der Injector schreibt nur die /AF-Kette und legt keinen Name-Tree-Eintrag an, also liegt eine über InjectAssociateFiles angehängte Datei außerhalb dieses Index; um die injizierte Kette zu bestätigen, inspizieren Sie die gespeicherten Bytes oder fahren einen PDF/A-Validator. Die Innereien dieses Name-Baums sind in Arbeiten mit PDF-Anhängungen in Delphi mit PDFium Component beschrieben
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; // eine leere Antwort wäre mehrdeutig, also nicht fragen
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;
Was garantiert SaveAsWithAssociateFiles nicht?
TPdf.SaveAsWithAssociateFiles garantiert den Dateiformat-Umschlag und dass die angeforderten Dateien injiziert wurden, nicht Konformität. Hatten die gespeicherten Bytes keinen lesbaren Trailer oder war das Katalog-Dictionary nicht auffindbar, wirft InjectAssociateFiles ein EPdfAssocFilesError, bevor irgendetwas geschrieben wird, und SaveAsWithAssociateFiles liefert False; weil die Methode die komplette Ausgabe in einem Save-Store aufbaut, bevor sie das Ziel öffnet, lässt eine abgelehnte oder gescheiterte Speicherung eine existierende Datei intakt. Ein leeres Files-Array kopiert das Dokument by Design unverändert durch. Der Inhalt der Payload ist ebenfalls Ihre Verantwortung: Der Injector prüft weder, ob eine XML-Datei wohlgeformt ist, ob der MIME-Typ zu den Bytes passt, noch ob das Basisdokument überhaupt PDF/A ist. Behandeln Sie die fertige Datei als unverifiziert, bis ein Validator sie gesehen hat – dieselbe Disziplin wie in PDFium Component und PDF/A-Archiv-Konformität beschrieben. Wer eingehende Dictionaries selbst parst, wendet dieselben #XX-Namensregeln rückwärts an, ein Thema, das in Name-Token-Fallen beim Parsen von PDF-Dictionaries behandelt wird
Associated Files, PDF/A-Ausgaben, Attachment-Metadaten und Validierung kommen alle in derselben Komponente, also läuft die Pipeline oben ohne eine zweite PDF-Bibliothek im Build. API-Referenz, Trial-Download und Lizenzoptionen finden Sie auf der PDFium Component product page