Artykuł techniczny

Pliki powiązane PDF/A-3 i AFRelationship w Delphi

Ż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

Łańcuch trzech obiektów pliku powiązanego PDF/A-3 w PDFium Component: strumień EmbeddedFile z MIME Subtype takim jak application xml, specyfikacja pliku z F, UF, EF i AFRelationship ustawionym na Data oraz tablica AF dla niego od katalogu albo strony — trzy obiekty, które walidator sprawdza, zanim przejdzie klauzula 6.8 ISO 19005-3
Strumień, specyfikacja pliku i tablica AF muszą się zgadzać; zwykłe osadzanie przez drzewo nazw w TPdf.CreateAttachment nie ustawia z założenia żadnego z pól powiązania

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 arkusz
  • afData → /Data: dane czytelne maszynowo, z których pochodzi widoczna treść albo które reprezentuje
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, 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

Dlaczego subtype MIME text slash plain połamał parsowanie PDF/A-3 w PDFium Component: sklejenie wartości po ukośniku produkowało dwa obiekty nazw, /text jako wartość plus wiszącą /plain rozbalansowującą słownik EmbeddedFile, a poprawka z v3.121.2 prowadzi wartość przez EscapePdfName, więc /text#2Fplain to jedna nazwa dekodująca się do text/plain
Awaria wyglądała jak uszkodzenie pliku, bo działo się to na parserze, przed jakąkolwiek regułą PDF/A; escapowana nazwa trzyma pary w równowadze i walidator czyta dalej
// 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

Gdzie ląduje tablica AF w PDFium Component: TargetPage zero przypina ją do katalogu, strony od 1 do N przypinają ją do słownika strony, a wartość poza zakresem rzuca wyjątek, przy czym injector dokleja wszystko jako jedną aktualizację inkrementalną w stałym układzie, który zachowuje istniejące offsety i zastępuje każdy wcześniejszy wpis AF
TargetPage poza zakresem rzuca zamiast po cichu stawać się powiązaniem poziomu dokumentu, a drugie wywołanie z inną listą plików wygrywa
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