Articolo tecnico

File associati PDF/A-3 e AFRelationship in Delphi

Per allegare un file sorgente a un documento PDF/A-3 da Delphi, PDFium Component scrive una catena di associated file PDF 2.0: uno stream di file incorporato con un /Subtype MIME, una file specification che porta /AFRelationship, e un array /AF appeso al catalogo o a una pagina. InjectAssociateFiles e TPdf.SaveAsWithAssociateFiles costruiscono quella catena in un unico aggiornamento incrementale, con il tipo MIME serializzato come un unico nome PDF correttamente escapato. Il resto di questo post copre che cosa controlla un validator, la trappola di un carattere che rompe text/plain, e i controlli che impediscono a un refuso o a un trailer illeggibile di produrre il file sbagliato

Che cosa serve davvero a un file associato PDF/A-3?

Un allegato PDF/A-3 passa la validazione solo quando tre oggetti sono d'accordo tra loro: lo stream del file incorporato dichiara /Type /EmbeddedFile più un /Subtype MIME, il dizionario di file specification (ISO 32000-2 §7.11.3) porta /F, /UF, /EF e /AFRelationship, e qualcosa nel documento referenzia quella file specification tramite un array /AF (ISO 32000-2 §14.13). L'incorporamento semplice attraverso l'albero /Names /EmbeddedFiles, che è ciò che fa TPdf.CreateAttachment, non imposta mai i campi di associazione. Un run di validazione PDF/A-3b rende concreta la dipendenza: rinominate solo la chiave /AFRelationship e il file fallisce esattamente una regola della clausola 6.8 di ISO 19005-3; togliete solo il /Subtype MIME e fallisce una diversa regola 6.8; mettete lo stesso allegato in un candidato PDF/A-1b e viene rifiutato seccamente, perché PDF/A-1 vieta i file incorporati non importa quanto siano ordinati i metadati

La catena a tre oggetti di un file associato PDF A-3 in PDFium Component: uno stream EmbeddedFile con un Subtype MIME come application xml, una file specification con F, UF, EF e AFRelationship impostato a Data, e un array AF per esso dal catalogo o da una pagina, i tre oggetti che un validator controlla prima che la clausola 6.8 di ISO 19005-3 passi
Stream, file specification e array AF devono essere d'accordo; l'incorporamento semplice nell'albero dei nomi di TPdf.CreateAttachment non imposta per design nessuno dei campi di associazione

Il valore della relazione è la parte su cui la gente tende a indovinare. TPdfAFRelationship in FPdfAssocFiles mappa un membro dell'enum a ogni name token che l'iniettore può emettere, e solo i primi cinque appartengono al sottoinsieme che ISO 19005-3 riconosce:

  • afSource → /Source: l'originale da cui il PDF è stato prodotto, come un file di videoscrittura o un foglio di calcolo
  • afData → /Data: dati leggibili dalla macchina da cui il contenuto visibile deriva o che rappresenta
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, afFormData, afTemplate: aggiunte PDF 2.0 che stanno fuori dal sottoinsieme PDF/A-3, quindi tenetele fuori dall'output di archivio

Perché /Subtype /text/plain rompe la validazione?

È un errore di tokenizzazione, non un buco di conformità. Concatenate la stringa del chiamante direttamente dopo una barra e ottenete /Subtype /text/plain. Nella sintassi PDF la seconda barra inizia un nuovo oggetto name (ISO 32000-1 §7.3.5), quindi il dizionario dello stream tiene improvvisamente la chiave /Subtype, il nome /text, e un nome extra pendente /plain che sbilancia le coppie chiave-valore. Un validator PDF/A indipendente rifiuta un file simile mentre analizza il dizionario EmbeddedFile, prima di arrivare mai a una regola PDF/A, ecco perché il fallimento sembra corruzione del file anziché una proprietà dell'allegato mancante

PDFium Component instrada il valore MIME attraverso EscapePdfName, che emette /text#2Fplain: un solo nome il cui valore decodificato è text/plain. L'escaping è volutamente più largo della barra. Ogni byte a 32 o sotto (spazio, tab, CR, LF), ogni byte a 127 o sopra, i delimitatori ()<>[]{}/% e il carattere di escape # stesso diventano #XX. Escapare solo la barra lascerebbe un buco diverso: una stringa MIME contenente >> o spazi bianchi potrebbe chiudere il dizionario in anticipo o iniettare chiavi extra

Perché il MIME subtype text slash plain rompe il parsing PDF A-3 in PDFium Component: concatenare il valore dopo una barra produce due oggetti name, /text come valore più un /plain pendente che sbilancia il dizionario EmbeddedFile, mentre EscapePdfName scrive /text#2Fplain come un nome che decodifica a text/plain
Il fallimento sembrava corruzione del file perché accadeva al parser, prima di ogni regola PDF/A; il nome escapato tiene le coppie bilanciate e il validator a leggere
// MIMEType = 'text/plain'
//   concatenazione ingenua:  /Type /EmbeddedFile /Subtype /text/plain     (due nomi)
//   output dell'iniettore:      /Type /EmbeddedFile /Subtype /text#2Fplain   (un nome)
//
// I chiamanti passano sempre il valore MIME ordinario. Pre-escaparlo da soli
// lo doppia-codifica: 'text#2Fplain' diventa 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';

Costruire un file PDF/A-3 con InjectAssociateFiles

Per l'output PDF/A-3, produrre il documento base conforme con TPdf.SaveAsPdfAToStream e poi chiamare InjectAssociateFiles su quello stream; quella pipeline a due passi è quella che passa la validazione PDF/A-3b. TPdf.SaveAsWithAssociateFiles è il wrapper di comodità, ma salva attraverso il percorso ordinario di SaveAs con saRemoveSecurity anziché attraverso il writer PDF/A, quindi non aggiunge l'identificazione XMP e l'output intent che PDF/A esige. Notate che i record types vivono in FPdfAssocFiles e FPdfPdfa, quindi entrambe le unit appartengono alla vostra clausola uses. Dalla v3.121.3, FileName e Description non sono limitati ad ASCII puro: /UF e /Desc vengono scritti come stringhe di testo PDF, l'ASCII stampabile letteralmente e tutto il resto come UTF-16BE con byte order mark, mentre il /F legacy è sempre ASCII stampabile portatile con ogni altro carattere sostituito da _, così i reader che decodificano /F con la propria code page mostrano un underscore invece di 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 a livello di catalogo
  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';  // scritto come /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);  // riavvolge Base; solleva EPdfAssocFilesError al fallimento
    finally
      Output.Free;
    end;
  finally
    Base.Free;
  end;
end;

Catalogo o pagina: dove atterra l'array /AF?

TAssocFilesOptions.TargetPage decide il proprietario dell'array /AF: 0 lo attacca al catalogo come associazione a livello di documento, e 1..N lo attacca al dizionario di quella pagina, in base 1. L'iniettore aggiunge tutto come un singolo aggiornamento incrementale in un layout fisso (gli stream incorporati, poi le file specification, poi l'array /AF, poi un catalogo o oggetto pagina riscritto), quindi gli oggetti esistenti conservano i loro offset e nulla viene ricompresso. Qualsiasi voce /AF precedente sul dizionario bersaglio viene sostituita, non fusa, il che rende un salvataggio ripetuto idempotente ma significa anche che una seconda chiamata con una lista di file diversa vince. TargetPage viene controllato in modo severo: SaveAsWithAssociateFiles e SaveAsWithAssociateFilesToStream sollevano EPdfError quando TargetPage sta fuori da 0..PageCount, e InjectAssociateFiles solleva EPdfAssocFilesError per un TargetPage negativo o che non nomina alcuna pagina esistente, lasciando lo stream di destinazione invariato, così un refuso non può trasformare di nascosto un'associazione a livello di pagina in una a livello di documento. TargetPage nomina la pagina in quella posizione nell'ordine delle pagine del documento. La trappola da evitare nel vostro codice è scansionare i byte salvati alla ricerca di dizionari /Type /Page in ordine di file: una volta che le pagine sono state riordinate o inserite, gli oggetti pagina possono essere memorizzati in un ordine diverso da quello di visualizzazione, e il file atterra su una pagina diversa

Dove atterra l'array AF in PDFium Component: TargetPage zero lo attacca al catalogo, le pagine da 1 a N lo attaccano al dizionario di pagina, e un valore fuori intervallo solleva un'eccezione, mentre l'iniettore aggiunge tutto come un aggiornamento incrementale unico in un layout fisso che conserva gli offset esistenti e sostituisce qualsiasi voce AF precedente
Un TargetPage fuori intervallo solleva invece di diventare di nascosto un'associazione a livello di documento, e una seconda chiamata con una lista di file diversa vince
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
  const CsvBytes: TBytes; const OutPath: string);
var
  Options: TAssocFilesOptions;
begin
  // Un TargetPage fuori intervallo solleva EPdfError; controllare prima
  // lascia all'errore di nominare la pagina
  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;

Come si rilegge AFRelationship in modo affidabile?

TPdf.AttachmentRelationship[Index] restituisce il nome /AFRelationship di un allegato tramite l'export nativo FPDFAttachment_GetAFRelationship, ma una stringa vuota ha due significati possibili, quindi chiamate prima AttachmentRelationshipFeaturesAvailable. Il binding viene caricato in modo tollerante: quando la DLL PDFium manca di quell'export, ogni relazione si legge come vuota, il che è indistinguibile da una file specification che semplicemente non ha /AFRelationship. La proprietà condivide il suo indice con AttachmentCount, che conta le voci nell'albero /Names /EmbeddedFiles. L'iniettore scrive solo la catena /AF e non aggiunge una voce all'albero dei nomi, quindi un file allegato tramite InjectAssociateFiles sta fuori da quell'indice; per confermare la catena iniettata, ispezionate i byte salvati o eseguite un validator PDF/A. Le interiorità di quell'albero dei nomi sono trattate in lavorare con gli allegati PDF in Delphi usando 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;  // una risposta vuota sarebbe ambigua, quindi non chiedete
  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;

Che cosa SaveAsWithAssociateFiles non garantisce?

TPdf.SaveAsWithAssociateFiles garantisce l'involucro del formato file e che i file richiesti siano stati iniettati, non la conformità. Quando i byte salvati non hanno un trailer leggibile o il dizionario catalogo non è individuabile, InjectAssociateFiles solleva EPdfAssocFilesError prima di scrivere qualsiasi cosa e SaveAsWithAssociateFiles restituisce False; poiché il metodo costruisce l'output completo in uno store di salvataggio prima di aprire il bersaglio, un salvataggio rifiutato o fallito lascia intatto un file esistente. Un array Files vuoto copia il documento invariato per design. Anche il contenuto del payload è responsabilità vostra: l'iniettore non controlla che un file XML sia ben formato, che il tipo MIME corrisponda ai byte, o che il documento base sia PDF/A a tutti gli effetti. Trattate il file finale come non verificato finché un validator non l'ha visto, la stessa disciplina descritta in PDFium Component e conformità archivistica PDF/A. Se analizzate anche voi i dizionari in ingresso, le stesse regole dei nomi #XX valgono al contrario, argomento trattato in le trappole dei name token nell'analizzare dizionari PDF

File associati, output PDF/A, metadati degli allegati e validazione viaggiano tutti nello stesso componente, quindi la pipeline sopra gira senza una seconda libreria PDF nel build. Il riferimento API, il download della trial e le opzioni di licenza sono sulla pagina del prodotto PDFium Component