EmbedFileA

Свойства документа

Описание

Завершающая A обозначает точку входа DLL типа ANSI (char); интерфейс ActiveX/COM предоставляет только форму Unicode. Поведение идентично EmbedFile, а строковые аргументы интерпретируются с использованием текущей кодовой страницы SetAnsiMode

Встраивает внешний файл в PDF и регистрирует его как вложение уровня документа; Acrobat и другие читалки показывают такие вложения в боковой панели Attachments. Вызов — сокращение для AddEmbeddedFile и следующего за ним AddToFileList: файл сохраняется потоком встроенного файла, а ссылающаяся на него запись под переданным заголовком добавляется в дерево имён Catalog /Names /EmbeddedFiles

Поведение версий PDF: потоки встроенных файлов и словари файловых спецификаций требуют PDF 1.3, а дерево имён уровня документа /Names /EmbeddedFiles, используемое этим удобным вызовом, — PDF 1.4. Если версия документа ниже, а версия сохранения не зафиксирована, EmbedFile автоматически поднимает документ до PDF 1.4 и записывает /EmbeddedFiles name tree в AutoBumpedFeatures. Если вызывающий зафиксировал более низкую версию сохранения, шлюз совместимости отклоняет сохранение с LastErrorCode 602

Синтаксис

Delphi

Function DLEmbedFileA(InstanceID: Integer; Title, FileName, MIMEType: PAnsiChar): Integer;

DLL

int DLEmbedFileA(int InstanceID, const char * Title, const char * FileName, const char * MIMEType);

Параметры

Title	Отображаемое имя в панели вложений читалки и ключ в дереве имён `/EmbeddedFiles`; должно быть уникальным в документе — если файл с таким заголовком уже есть, вызов завершится ошибкой
FileName	Полный путь исходного файла на диске; байты файла копируются в PDF
MIMEType	Тип MIME, определяющий содержимое файла (например, `image/jpeg`, `text/csv`, `application/xml`). Передайте пустую строку, если тип MIME неизвестен; средства просмотра будут ориентироваться на расширение файла.

Возвращаемые значения

0	Не удалось встроить файл — файл-источник отсутствует, заголовок уже используется либо не открыт ни один документ.
1	Файл встроен и внесён в дерево имён вложений документа

Примечания

Этот вызов лишь создаёт вложение уровня документа. Чтобы нарисовать на конкретной странице кликабельную аннотацию-скрепку, указывающую на встроенный файл, используйте связку AddEmbeddedFile и AddFileAttachment (или AddLinkToEmbeddedFile)

PDF/A compatibility:

PDF/A-1 и PDF/A-2 (режимы 1–4 SetPDFAMode) запрещают произвольные встроенные файлы. Защита PDF/A блокирует EmbedFile в этих режимах.
PDF/A-3 (режимы 5, 6 и 7) разрешает встроенные файлы любого MIME-типа. ISO 19005-3 также требует, чтобы каждый встроенный файл декларировал свою связь с документом через ключ AFRelationship — задайте его явно с помощью SetEmbeddedFileAFRelationship.

Когда активен SetPDFUAMode, библиотека автоматически записывает AFRelationship=Unspecified для любого встроенного файла без явной связи; чтобы выполнить ISO 14289-1 §7.11, переопределите её через SetEmbeddedFileAFRelationship.

Пример

// Embed a CSV of the source data as a document attachment
PDF.NewDocument;
PDF.AddStandardFont('Helvetica');
PDF.AddPage;
PDF.PrintText(50, 750, 'Sales summary, Q1 2026');

if PDF.EmbedFile('Source data — sales-Q1.csv', 'C:\reports\sales-Q1.csv', 'text/csv') = 1 then
  WriteLn('Attachment added')
else
  WriteLn('Failed to embed file');

PDF.SaveToFile('Q1-Summary.pdf');

См. также

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode