Artículo técnico

Archivos asociados de PDF/A-3 y AFRelationship en Delphi

Para adjuntar un archivo fuente a un documento PDF/A-3 desde Delphi, PDFium Component escribe una cadena de associated files de PDF 2.0: un embedded file stream con /Subtype MIME, una file specification que carga /AFRelationship, y un array /AF colgado del catálogo o de una página. InjectAssociateFiles y TPdf.SaveAsWithAssociateFiles construyen esa cadena en una sola actualización incremental, con el tipo MIME serializado como un único nombre PDF correctamente escapado. El resto de este post cubre qué revisa un validador, la trampa de un solo carácter que rompe text/plain, y los chequeos que evitan que un typo o un trailer ilegible produzca el archivo equivocado

¿Qué necesita realmente un archivo asociado de PDF/A-3?

Un adjunto PDF/A-3 pasa la validación solo cuando tres objetos están de acuerdo entre sí: el embedded file stream declara /Type /EmbeddedFile más un /Subtype MIME, el diccionario de file specification (ISO 32000-2 §7.11.3) carga /F, /UF, /EF y /AFRelationship, y algo en el documento referencia esa file specification vía un array /AF (ISO 32000-2 §14.13). El embebido plain por el árbol /Names /EmbeddedFiles, que es lo que hace TPdf.CreateAttachment, no asigna los campos de asociación para nada. Una corrida de validación PDF/A-3b vuelve concreta la dependencia: renombre solo la clave /AFRelationship y el archivo falla exactamente una regla de la cláusula 6.8 de ISO 19005-3; quite solo el /Subtype MIME y falla una regla 6.8 distinta; meta el mismo adjunto en un candidato PDF/A-1b y lo rechazan de plano, porque PDF/A-1 prohíbe archivos embebidos sin importar qué tan prolijo esté el metadata

La cadena de tres objetos de un associated file de PDF A-3 en PDFium Component: un stream EmbeddedFile con un Subtype MIME como application xml, una file specification con F, UF, EF y AFRelationship en Data, y un array AF para ella desde el catálogo o una página, los tres objetos que revisa un validador antes de que la cláusula 6.8 de ISO 19005-3 pase
Stream, file specification y array AF deben estar de acuerdo; el embebido plain por árbol de nombres de TPdf.CreateAttachment no asigna ninguno de los campos de asociación por diseño

El valor de relationship es la parte que la gente suele adivinar. TPdfAFRelationship en FPdfAssocFiles mapea un miembro del enum a cada token de nombre que el inyector puede emitir, y solo los primeros cinco pertenecen al subconjunto que ISO 19005-3 reconoce:

  • afSource → /Source: el original del que se produjo el PDF, como un archivo de procesador de textos o una planilla
  • afData → /Data: datos legibles por máquina de los que se derivó o que representa el contenido visible
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, afFormData, afTemplate: adiciones de PDF 2.0 que caen fuera del subconjunto PDF/A-3, así que téngalos lejos de la salida de archivo

¿Por qué /Subtype /text/plain rompe la validación?

Es un error de tokenización, no un faltante de compliance. Concatene el string del llamador directo después de una barra y obtiene /Subtype /text/plain. En sintaxis PDF la segunda barra arranca un nuevo objeto name (ISO 32000-1 §7.3.5), así que el diccionario del stream de repente guarda la clave /Subtype, el nombre /text, y un nombre extra colgante /plain que desbalancea los pares clave-valor. Un validador PDF/A independiente rechaza semejante archivo mientras parsea el diccionario EmbeddedFile, antes de llegar jamás a una regla PDF/A, razón por la cual el fallo se ve como corrupción de archivo en vez de una propiedad de adjunto faltante

PDFium Component enruta el valor MIME vía EscapePdfName, que emite /text#2Fplain: un solo nombre cuyo valor decodificado es text/plain. El escaping es deliberadamente más ancho que la barra. Todo byte en 32 o menos (espacio, tab, CR, LF), todo byte en 127 o más, los delimitadores ()<>[]{}/% y el propio carácter de escape # se vuelven #XX. Escapar solo la barra dejaría un agujero distinto: un string MIME que contenga >> o whitespace podría cerrar el diccionario antes de tiempo o inyectar claves extra

Por qué el subtipo MIME text slash plain rompe el parseo de PDF A-3 en PDFium Component: concatenar el valor después de una barra produce dos objetos name, /text como valor más un /plain colgante que desbalancea el diccionario EmbeddedFile, mientras EscapePdfName escribe /text#2Fplain como un nombre que decodifica a text/plain
El fallo se veía como corrupción de archivo porque pasó en el parser, antes de cualquier regla PDF/A; el nombre escapado mantiene los pares balanceados y al validador leyendo
// Lo que el inyector escribe para MIMEType = 'text/plain'
//   concatenación ingenua: /Type /EmbeddedFile /Subtype /text/plain     (dos nombres)
//   salida del injector:   /Type /EmbeddedFile /Subtype /text#2Fplain   (un nombre)
//
// Los llamadores siempre pasan el valor MIME ordinario. Pre-escapearlo usted
// mismo duplica el encode del '#', lo que vuelve 'text#2Fplain' en 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';

Construir un archivo PDF/A-3 con InjectAssociateFiles

Para salida PDF/A-3, produzca el documento base conforme con TPdf.SaveAsPdfAToStream y luego llame a InjectAssociateFiles sobre ese stream; ese pipeline de dos pasos es el que pasa la validación PDF/A-3b. TPdf.SaveAsWithAssociateFiles es el wrapper de conveniencia, pero guarda por el camino ordinario de SaveAs con saRemoveSecurity en vez de por el escritor PDF/A, así que no agrega la identificación XMP ni el output intent que PDF/A exige. Note que los record types viven en FPdfAssocFiles y FPdfPdfa, así que ambas unidades pertenecen a su cláusula uses. Desde la v3.121.3, FileName y Description no están limitadas a ASCII plain: /UF y /Desc se escriben como text strings de PDF, el ASCII imprimible literal y cualquier otra cosa como UTF-16BE con byte order mark, mientras el nombre /F legado siempre es ASCII imprimible portable con cada otro carácter reemplazado por _, así que los lectores que decodifican /F con su propia code page muestran un underscore en vez de 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 nivel de catálogo
  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';  // se escribe como /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);  // rebobina Base; lanza EPdfAssocFilesError en fallo
    finally
      Output.Free;
    end;
  finally
    Base.Free;
  end;
end;

Catálogo o página: ¿dónde aterriza el array /AF?

TAssocFilesOptions.TargetPage decide el dueño del array /AF: 0 lo adjunta al catálogo como asociación a nivel de documento, y 1..N lo adjunta al diccionario de esa página, base 1. El injector agrega todo como una única actualización incremental en un layout fijo (los streams embebidos, luego las file specifications, luego el array /AF, luego un catálogo u objeto de página reescrito), así que los objetos existentes conservan sus offsets y nada se recomprime. Cualquier entrada /AF anterior en el diccionario destino se reemplaza, no se mezcla, lo que hace idempotente un guardado repetido pero también implica que una segunda llamada con una lista de archivos distinta gana. TargetPage se chequea estrictamente: SaveAsWithAssociateFiles y SaveAsWithAssociateFilesToStream levantan EPdfError cuando TargetPage está fuera de 0..PageCount, y InjectAssociateFiles levanta EPdfAssocFilesError para un TargetPage negativo o uno que no nombra ninguna página existente, dejando el stream destino sin modificar, así que un typo no puede convertir en silencio una asociación de página en una de documento. TargetPage nombra la página en esa posición del orden de páginas del documento. La trampa que hay que evitar en su propio código es escanear los bytes guardados buscando diccionarios /Type /Page en orden de archivo: una vez que las páginas se reordenan o insertan, los objetos de página pueden quedar almacenados en otro orden al que se muestran, y el archivo aterriza en una página distinta

Dónde aterriza el array AF en PDFium Component: TargetPage cero lo adjunta al catálogo, las páginas 1 a N lo adjuntan al diccionario de página, y un valor fuera de rango levanta una excepción, mientras el injector agrega todo como una actualización incremental en un layout fijo que conserva los offsets existentes y reemplaza cualquier entrada AF anterior
Un TargetPage fuera de rango levanta excepción en vez de volverse en silencio una asociación a nivel de documento, y una segunda llamada con una lista de archivos distinta gana
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
  const CsvBytes: TBytes; const OutPath: string);
var
  Options: TAssocFilesOptions;
begin
  // Un TargetPage fuera de rango levanta EPdfError; chequear primero deja que
  // el error nombre la página
  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;

¿Cómo se lee AFRelationship de vuelta con confianza?

TPdf.AttachmentRelationship[Index] devuelve el nombre /AFRelationship de un adjunto vía el export nativo FPDFAttachment_GetAFRelationship, pero un string vacío tiene dos significados posibles, así que llame primero a AttachmentRelationshipFeaturesAvailable. El binding se carga con tolerancia: cuando la DLL de PDFium carece de ese export, toda relationship se lee vacía, lo que es indistinguible de una file specification que simplemente no tiene /AFRelationship. La propiedad además comparte su índice con AttachmentCount, que cuenta entradas del árbol /Names /EmbeddedFiles. El inyector escribe solo la cadena /AF y no agrega entrada al name-tree, así que un archivo adjuntado vía InjectAssociateFiles queda fuera de ese índice; para confirmar la cadena inyectada, inspeccione los bytes guardados o corra un validador PDF/A. Las interioridades de ese name-tree están cubiertas en trabajar con adjuntos PDF en 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 respuesta vacía sería ambigua, así que no pregunte
  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;

¿Qué no garantiza SaveAsWithAssociateFiles?

TPdf.SaveAsWithAssociateFiles garantiza el envelope de formato de archivo y que los archivos pedidos fueron inyectados, no la conformidad. Cuando los bytes guardados no tienen trailer legible o el diccionario del catálogo no se puede ubicar, InjectAssociateFiles levanta EPdfAssocFilesError antes de escribir nada y SaveAsWithAssociateFiles devuelve False; como el método construye la salida completa en un save store antes de abrir el destino, un guardado rechazado o fallido deja un archivo existente intacto. Un array Files vacío copia el documento sin cambios a propósito. El contenido del payload también es responsabilidad suya: el injector no chequea que un archivo XML esté bien formado, que el tipo MIME coincida con los bytes, ni que el documento base sea PDF/A en lo absoluto. Trate el archivo final como no verificado hasta que un validador lo haya visto, la misma disciplina descrita en PDFium Component y compliance de archivo PDF/A. Si usted además parsea diccionarios entrantes por su cuenta, las mismas reglas de nombres #XX aplican al revés, tema cubierto en trampas de tokens de nombre al parsear diccionarios PDF

Associated files, salida PDF/A, metadata de adjuntos y validación vienen todos en el mismo componente, así que el pipeline de arriba corre sin una segunda librería PDF en el build. La referencia del API, la descarga de prueba y las opciones de licencia están en la página de producto de PDFium Component