Чтобы прикрепить файл-источник к документу PDF/A-3 из Delphi, PDFium Component пишет цепочку ассоциированных файлов PDF 2.0: stream встроенного файла с MIME /Subtype, file specification с /AFRelationship и массив /AF, подвешенный на каталог или страницу. InjectAssociateFiles и TPdf.SaveAsWithAssociateFiles собирают ту цепочку одним инкрементальным обновлением, с MIME-типом, сериализуемым как единственное, корректно экранированное PDF-имя. Остаток поста — о том, что проверяет валидатор, об односимвольной ловушке, ломающей text/plain, и о проверках, которые не дают опечатке или нечитаемому trailer произвести не тот файл
Что ассоциированному файлу PDF/A-3 действительно нужно?
Вложение PDF/A-3 проходит валидацию, только когда три объекта согласны друг с другом: stream встроенного файла объявляет /Type /EmbeddedFile плюс MIME /Subtype, словарь file specification (ISO 32000-2 §7.11.3) несёт /F, /UF, /EF и /AFRelationship, а нечто в документе ссылается на ту file specification через массив /AF (ISO 32000-2 §14.13). Простое встраивание через дерево /Names /EmbeddedFiles — то, что делает TPdf.CreateAttachment, — ассоциативные поля не ставит вовсе. Прогон валидации PDF/A-3b делает зависимость осязаемой: переименуйте только ключ /AFRelationship, и файл проваливает ровно одно правило клаузы 6.8 ISO 19005-3; уберите только MIME /Subtype — и падает другое правило 6.8; положите то же вложение в кандидата PDF/A-1b — его отвергнут outright, потому что PDF/A-1 запрещает встроенные файлы, какими бы опрятными ни были метаданные
Значение relationship — та часть, которую обычно угадывают. TPdfAFRelationship в FPdfAssocFiles мапит по одному члену enum на каждый name-токен, который может выпустить инжектор, и лишь первые пять принадлежат подмножеству, которое признаёт ISO 19005-3:
afSource→/Source: оригинал, из которого произведён PDF, скажем файл текстового процессора или таблицаafData→/Data: машиночитаемые данные, из которых выведено или которые представляет видимое содержимоеafAlternative→/Alternative,afSupplement→/Supplement,afUnspecified→/UnspecifiedafEncryptedPayload,afFormData,afTemplate: добавления PDF 2.0, лежащие вне подмножества PDF/A-3, так что держите их подальше от архивного вывода
Почему /Subtype /text/plain ломает валидацию?
Это ошибка токенизации, а не дыра в соответствии стандарту. Склейте строку вызывающего прямо после слэша — и получите /Subtype /text/plain. По синтаксису PDF второй слэш начинает новый name-объект (ISO 32000-1 §7.3.5), поэтому в словаре stream внезапно оказываются ключ /Subtype, имя /text и болтающееся лишнее имя /plain, разбалансировывающее пары ключ-значение. Независимый валидатор PDF/A отвергает такой файл ещё при разборе словаря EmbeddedFile, не добравшись ни до одного правила PDF/A, — оттого отказ и выглядит как повреждение файла, а не как недостающее свойство вложения
PDFium Component прогоняет MIME-значение через EscapePdfName, который выдаёт /text#2Fplain: одно имя, чьё декодированное значение — text/plain. Экранирование нарочно шире одного слэша. Каждый байт со значением 32 и ниже (пробел, таб, CR, LF), каждый байт 127 и выше, разделители ()<>[]{}/% и сам escape-символ # становятся #XX. Экранирование одного лишь слэша оставило бы другую дыру: MIME-строка с >> или whitespace могла бы закрыть словарь раньше времени или вписать лишние ключи
// MIMEType = 'text/plain'
// наивная склейка: /Type /EmbeddedFile /Subtype /text/plain (два имени)
// вывод инжектора: /Type /EmbeddedFile /Subtype /text#2Fplain (одно имя)
//
// Вызывающие всегда передают обычное значение MIME. Пре-эскейп его своими
// руками двойным кодирует '#', превращая 'text#2Fplain' в 'text#232Fplain'
Options.Files[0].MIMEType := 'text/plain';
Сборка файла PDF/A-3 через InjectAssociateFiles
Для вывода PDF/A-3 соберите соответствующий стандарту базовый документ через TPdf.SaveAsPdfAToStream и затем позовите InjectAssociateFiles на том stream'е; именно тот двухшаговый конвейер проходит валидацию PDF/A-3b. TPdf.SaveAsWithAssociateFiles — обёртка для удобства, но она сохраняет через обычный путь SaveAs с saRemoveSecurity, а не через PDF/A-писатель, так что XMP-идентификацию и output intent, которых требует PDF/A, не добавляет. Заметьте, что типы записей живут в FPdfAssocFiles и FPdfPdfa, так что оба юнита должны быть в вашей клаузе uses. С v3.121.3 FileName и Description не ограничены чистым ASCII: /UF и /Desc пишутся как PDF text strings — печатный ASCII буквально, всё прочее как UTF-16BE с byte order mark, — тогда как legacy-имя /F всегда portable printable ASCII, где любой другой символ заменён на _, чтобы читатели, декодирующие /F собственной кодовой страницей, видели подчёркивание вместо 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 уровня каталога
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'; // пишется как /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); // перематывает Base; при сбое EPdfAssocFilesError
finally
Output.Free;
end;
finally
Base.Free;
end;
end;
Каталог или страница: куда приземляется массив /AF?
TAssocFilesOptions.TargetPage решает, кто владеет массивом /AF: 0 прикрепляет его к каталогу как ассоциацию уровня документа, а 1..N — к словарю той страницы, с нумерацией от единицы. Инжектор дописывает всё одним инкрементальным обновлением в фиксированной раскладке (встроенные stream'ы, затем file specifications, затем массив /AF, затем переписанный каталог или объект страницы), так что существующие объекты сохраняют смещения и ничего не перекомпрессируется. Любая более ранняя запись /AF на целевом словаре заменяется, а не мержится, что делает повторное сохранение идемпотентным, но также означает, что второй вызов с другим списком файлов побеждает. TargetPage проверяется строго: SaveAsWithAssociateFiles и SaveAsWithAssociateFilesToStream поднимают EPdfError, когда TargetPage вне 0..PageCount, а InjectAssociateFiles поднимает EPdfAssocFilesError на отрицательном TargetPage или том, что не называет существующую страницу, оставляя целевой stream нетронутым, — опечатка не может тихо превратить ассоциацию уровня страницы в ассоциацию уровня документа. TargetPage называет страницу на той позиции в порядке страниц документа. Ловушка, которой стоит избегать в собственном коде, — сканирование сохранённых байтов на словари /Type /Page в файловом порядке: стоит страницам быть переставленными или вставленными, и объекты страниц могут лежать в файле не в том порядке, в каком отображаются, — файл приземлится на другой странице
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
const CsvBytes: TBytes; const OutPath: string);
var
Options: TAssocFilesOptions;
begin
// TargetPage вне диапазона поднимает EPdfError; проверка сперва позволяет
// ошибке назвать страницу
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;
Как надёжно прочитать AFRelationship обратно?
TPdf.AttachmentRelationship[Index] возвращает имя /AFRelationship вложения через нативный экспорт FPDFAttachment_GetAFRelationship, но у пустой строки два возможных смысла, так что сперва позовите AttachmentRelationshipFeaturesAvailable. Биндинг грузится снисходительно: когда в PDFium DLL нет того экспорта, каждая relationship читается как пустая, что неотличимо от file specification, у которой просто нет /AFRelationship. Свойство делит индекс с AttachmentCount, считающим записи в дереве /Names /EmbeddedFiles. Инжектор пишет только цепочку /AF и не добавляет записи в name-tree, так что файл, прикреплённый через InjectAssociateFiles, лежит вне того индекса; чтобы подтвердить инжектированную цепочку, осмотрите сохранённые байты или прогоните валидатор PDF/A. Внутренности того name-tree разобраны в статье о работе с PDF-вложениями в Delphi через 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; // пустой ответ был бы двусмысленным, так что не спрашиваем
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;
Чего SaveAsWithAssociateFiles не гарантирует?
TPdf.SaveAsWithAssociateFiles гарантирует файлово-форматную обёртку и то, что запрошенные файлы были инжектированы, — но не соответствие стандарту. Когда в сохранённых байтах нет читаемого trailer или словарь каталога не удаётся отыскать, InjectAssociateFiles поднимает EPdfAssocFilesError до записи чего-либо, а SaveAsWithAssociateFiles возвращает False; поскольку метод собирает полный вывод в save store до открытия цели, отвергнутое или провалившееся сохранение оставляет существующий файл целым. Пустой массив Files по замыслу прокапывает документ нетронутым. Содержимое полезной нагрузки — тоже ваша забота: инжектор не проверяет, что XML-файл well-formed, что MIME-тип совпадает с байтами или что базовый документ вообще PDF/A. Считайте финальный файл неверифицированным, пока его не увидел валидатор, — та же дисциплина, что описана в статье о PDFium Component и архивном соответствии PDF/A. Если вы и входящие словари парсите сами, те же правила имён #XX работают в обратную сторону — тема разобрана в статье о ловушках name-токенов при парсинге PDF-словарей
Ассоциированные файлы, вывод PDF/A, метаданные вложений и валидация едут в одном компоненте, так что конвейер выше работает без второй PDF-библиотеки в сборке. Справочник API, пробная загрузка и варианты лицензирования — на странице продукта PDFium Component