Żeby załączyć plik źródłowy do dokumentu PDF/A-3 z Delphi, PDFium Component zapisuje łańcuch pliku powiązanego PDF 2.0: strumień osadzonego pliku z MIME /Subtype, specyfikację pliku niosącą /AFRelationship i tablicę /AF powieszoną na katalogu albo stronie. InjectAssociateFiles i TPdf.SaveAsWithAssociateFiles budują ten łańcuch w jednej aktualizacji inkrementalnej, z typem MIME serializowanym jako pojedyncza, poprawnie escapowana nazwa PDF. Reszta tego tekstu pokrywa, co sprawdza walidator, jednoznakową pułapkę łamiącą text/plain i sprawdzenia, które nie pozwalają literówce albo nieczytelnemu trailerowi wyprodukować złego pliku
Czego faktycznie potrzebuje plik powiązany PDF/A-3?
Załącznik PDF/A-3 przechodzi walidację tylko wtedy, gdy trzy obiekty zgadzają się ze sobą: strumień osadzonego pliku deklaruje /Type /EmbeddedFile plus MIME /Subtype, słownik specyfikacji pliku (ISO 32000-2 §7.11.3) niesie /F, /UF, /EF i /AFRelationship, a coś w dokumencie referencjonuje tę specyfikację pliku przez tablicę /AF (ISO 32000-2 §14.13). Zwykłe osadzanie przez drzewo /Names /EmbeddedFiles, co robi TPdf.CreateAttachment, w ogóle nie ustawia pól powiązania. Przebieg walidacji PDF/A-3b robi z tą zależnością konkret: przemień tylko klucz /AFRelationship i plik zawodzi na dokładnie jednej regule klauzuli 6.8 ISO 19005-3; zdejmij tylko MIME /Subtype i zawodzi inna reguła 6.8; włóż ten sam załącznik do kandydata PDF/A-1b i zostanie odrzucony w całości, bo PDF/A-1 zakazuje osadzonych plików, niezależnie od tego, jak schludne są metadane
Wartość relacji to ta część, którą ludzie lubią zgadywać. TPdfAFRelationship w FPdfAssocFiles mapuje po jednym członku enuma na każdy token nazwy, jaki injector potrafi wyemitować, i tylko pierwsze pięć należy do podzbioru rozpoznawanego przez ISO 19005-3:
afSource→/Source: oryginał, z którego powstał PDF, na przykład plik edytora tekstu albo arkuszafData→/Data: dane czytelne maszynowo, z których pochodzi widoczna treść albo które reprezentujeafAlternative→/Alternative,afSupplement→/Supplement,afUnspecified→/UnspecifiedafEncryptedPayload,afFormData,afTemplate: dodatki PDF 2.0 wypadające poza podzbiór PDF/A-3, więc trzymaj je z dala od wyjścia archiwalnego
Dlaczego /Subtype /text/plain łamie walidację?
To błąd tokenizacji, nie luka zgodności. Sklej łańcuch wywołującego wprost po ukośniku, a dostaniesz /Subtype /text/plain. W składni PDF drugi ukośnik zaczyna nowy obiekt nazwy (ISO 32000-1 §7.3.5), więc słownik strumienia nagle trzyma klucz /Subtype, nazwę /text i wiszącą dodatkową nazwę /plain, która rozbalansowuje pary klucz-wartość. Niezależny walidator PDF/A odrzuca taki plik przy parsowaniu słownika EmbeddedFile, zanim w ogóle dojdzie do reguły PDF/A, dlatego awaria wygląda jak uszkodzenie pliku, a nie brakująca właściwość załącznika
PDFium Component prowadzi wartość MIME przez EscapePdfName, które emituje /text#2Fplain: jedną nazwę, której zdekodowana wartość to text/plain. Escapowanie jest celowo szersze niż ukośnik. Każdy bajt równy 32 lub niższy (spacja, tabulator, CR, LF), każdy bajt równy 127 lub wyższy, delimetry ()<>[]{}/% i sam znak ucieczki # stają się #XX. Escapowanie tylko ukośnika zostawiałoby inną dziurę: łańcuch MIME zawierający >> albo biały znak mógłby zamknąć słownik za wcześnie albo wstrzyknąć dodatkowe klucze
// MIMEType = 'text/plain'
// naiwne sklejenie: /Type /EmbeddedFile /Subtype /text/plain (dwie nazwy)
// wyjście injectora: /Type /EmbeddedFile /Subtype /text#2Fplain (jedna nazwa)
//
// Wywołujący zawsze podają zwykłą wartość MIME. Pre-escapowanie jej samemu
// podwójnie koduje '#', co zamienia 'text#2Fplain' w 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';
Budowanie pliku PDF/A-3 z InjectAssociateFiles
Dla wyjścia PDF/A-3 wyprodukuj zgodny dokument bazowy przez TPdf.SaveAsPdfAToStream, a potem zawołaj InjectAssociateFiles na tym strumieniu; to dwuetapowy potok, który przechodzi walidację PDF/A-3b. TPdf.SaveAsWithAssociateFiles to wygodny wrapper, ale zapisuje zwykłą ścieżką SaveAs z saRemoveSecurity, a nie przez pisarza PDF/A, więc nie dodaje identyfikacji XMP ani output intent, których PDF/A wymaga. Zauważ, że typy rekordów mieszkają w FPdfAssocFiles i FPdfPdfa, więc obie jednostki należą do twojej klauzuli uses. Od v3.121.3 FileName i Description nie są ograniczone do zwykłego ASCII: /UF i /Desc są zapisywane jako tekstowe łańcuchy PDF — drukowalne ASCII dosłownie, a wszystko inne jako UTF-16BE ze znacznikiem kolejności bajtów — podczas gdy legacy'owa nazwa /F to zawsze przenośne drukowalne ASCII z każdym innym znakiem zastąpionym przez _, więc czytniki, które dekodują /F własną stroną kodową, pokazują podkreślnik zamiast krzaków
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 na poziomie dokumentu
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'; // zapisywane jako /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); // przewija Base; rzuca EPdfAssocFilesError
finally
Output.Free;
end;
finally
Base.Free;
end;
end;
Katalog albo strona: gdzie ląduje tablica /AF?
TAssocFilesOptions.TargetPage rozstrzyga, czyj jest tablica /AF: 0 przypina ją do katalogu jako powiązanie poziomu dokumentu, a 1..N do słownika tamtej strony, numerowanej od 1. Injector dokleja wszystko jako pojedynczą aktualizację inkrementalną w stałym układzie (osadzone strumienie, potem specyfikacje plików, potem tablica /AF, potem przepisany katalog albo obiekt strony), więc istniejące obiekty zachowują swoje offsety i nic nie jest rekompresowane. Każdy wcześniejszy wpis /AF na słowniku celu jest zastępowany, nie scalany, co czyni powtórny zapis idempotentnym, ale znaczy też, że drugie wywołanie z inną listą plików wygrywa. TargetPage jest sprawdzany surowo: SaveAsWithAssociateFiles i SaveAsWithAssociateFilesToStream rzucają EPdfError, gdy TargetPage jest poza 0..PageCount, a InjectAssociateFiles rzuca EPdfAssocFilesError dla ujemnego TargetPage albo takiego, który nie nazywa istniejącej strony, zostawiając strumień docelowy nietknięty, więc literówka nie zamieni po cichu powiązania poziomu strony w poziom dokumentu. TargetPage nazywa stronę na tej pozycji w kolejności stron dokumentu. Pułapka do uniknięcia we własnym kodzie to skanowanie zapisanych bajtów za słownikami /Type /Page w kolejności plikowej: gdy strony zostaną przestawione albo wstawione, obiekty stron mogą być przechowywane w innej kolejności niż są wyświetlane, i plik wyląduje na innej stronie
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
const CsvBytes: TBytes; const OutPath: string);
var
Options: TAssocFilesOptions;
begin
// TargetPage poza zakresem podnosi EPdfError; sprawdzenie najpierw pozwala
// błędowi nazwać stronę
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;
Jak czytać AFRelationship z powrotem niezawodnie?
TPdf.AttachmentRelationship[Index] zwraca nazwę /AFRelationship załącznika przez natywny eksport FPDFAttachment_GetAFRelationship, ale pusty łańcuch ma dwa możliwe znaczenia, więc wołaj najpierw AttachmentRelationshipFeaturesAvailable. Wiązanie jest ładowane pobłażliwie: gdy DLL PDFium nie ma tego eksportu, każda relacja czyta się jako pusta, co jest nie do odróżnienia od specyfikacji pliku, która po prostu nie ma /AFRelationship. Właściwość dzieli też swój indeks z AttachmentCount, które liczy wpisy w drzewie /Names /EmbeddedFiles. Injector zapisuje tylko łańcuch /AF i nie dodaje wpisu w drzewie nazw, więc plik załączony przez InjectAssociateFiles jest poza tym indeksem; żeby potwierdzić wstrzyknięty łańcuch, obejrzyj zapisane bajty albo odpal walidator PDF/A. Wnętrza tego drzewa nazw opisuje praca z załącznikami PDF w Delphi z 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; // pusta odpowiedź byłaby wieloznaczna, więc nie pytaj
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;
Czego SaveAsWithAssociateFiles nie gwarantuje?
TPdf.SaveAsWithAssociateFiles gwarantuje kopertę formatu plikowego i to, że żądane pliki zostały wstrzyknięte, nie zgodność. Gdy zapisane bajty nie mają czytelnego trailera albo słownik katalogu nie daje się zlokalizować, InjectAssociateFiles rzuca EPdfAssocFilesError przed zapisaniem czegokolwiek, a SaveAsWithAssociateFiles zwraca False; ponieważ metoda buduje kompletne wyjście w save store przed otwarciem celu, odrzucony albo nieudany zapis zostawia istniejący plik nietknięty. Pusta tablica Files przepuszcza dokument bez zmian, z założenia. Za zawartość ładunku też odpowiadasz sam: injector nie sprawdza, czy plik XML jest well-formed, czy typ MIME pasuje do bajtów, ani czy dokument bazowy jest w ogóle PDF/A. Traktuj finalny plik jako niezweryfikowany, dopóki nie zobaczy go walidator — ta sama dyscyplina opisana w PDFium Component i zgodności archiwalnej PDF/A. Jeśli sam też parsujesz przychodzące słowniki, te same reguły nazw #XX obowiązują w odwrotną stronę, co opisuje pułapki tokenów nazw przy parsowaniu słowników PDF
Pliki powiązane, wyjście PDF/A, metadane załączników i walidacja płyną w tym samym komponencie, więc pipeline powyżej chodzi bez drugiej biblioteki PDF w projekcie. Referencja API, pobranie próbne i opcje licencjonowania są na stronie produktu PDFium Component