AddEmbeddedFile

Document properties

Description

Встраивает файл внутрь PDF как поток встроенного файла, но само по себе не регистрирует файл в списках каталога и не рисует интерактивную аннотацию; функция возвращает дескриптор EmbeddedFileID, который можно передать в AddFileAttachment (чтобы прикрепить значок скрепки на страницу) или AddLinkToEmbeddedFile (чтобы создать кликабельную область, открывающую файл); чтобы одновременно внедрить файл и внести его в список вложений уровня документа за один вызов, используйте вместо этого EmbedFile

Syntax

Delphi

Function TPDFlib.AddEmbeddedFile(Const FileName, MIMEType: WideString): Integer;

ActiveX

Function PDFlib::AddEmbeddedFile(FileName As String, MIMEType As String) As Long

DLL

int DLAddEmbeddedFile(int InstanceID, const wchar_t * FileName, const wchar_t * MIMEType);

Parameters

FileName	Полный путь и имя исходного файла на диске; его байты копируются дословно во встроенный файловый поток PDF
MIMEType	MIME-тип файла, например `image/jpeg` или `application/xml`; может быть пустой строкой, если тип MIME неизвестен

Return values

0	Не удалось открыть файл или нет активного документа
Non-zero	Дескриптор EmbeddedFileID для использования с AddFileAttachment, AddLinkToEmbeddedFile, или SetEmbeddedFileStrProperty

Remarks

PDF version behavior: embedded file streams and file specification dictionaries require PDF 1.3. If the current document version is lower and the save version is not locked, AddEmbeddedFile automatically raises the document to PDF 1.3. Calls that register the file as a document-level attachment can require a higher version: AddFileAttachment and EmbedFile use the PDF 1.4 /Names /EmbeddedFiles name tree, and AddLinkToEmbeddedFile uses PDF 1.4 annotation opacity/appearance transparency.

Файл, встроенный только с помощью AddEmbeddedFile, является частью PDF, но невидим в интерфейсе программы чтения, пока он не зарегистрирован в списке вложений документа или на него нет ссылки из аннотации страницы; повторное использование одного и того же дескриптора EmbeddedFileID с AddFileAttachment и AddLinkToEmbeddedFile позволяет представить один встроенный файл как через интерфейс уровня документа, так и через уровень страницы без дублирования встроенных байтов

PDF/A compatibility:

PDF/A-1, PDF/A-2 (SetPDFAMode modes 1–4) — embedded files are forbidden; the call is rejected.
PDF/A-3 (SetPDFAMode modes 5, 6, and 7) — embedded files of any MIME type are permitted. Set the file's relationship via SetEmbeddedFileAFRelationship before saving.

Example

// Expose the same embedded file through the document attachment list and a page annotation
var
  FileID: Integer;
begin
  PDF.NewDocument;
  PDF.AddStandardFont('Helvetica');

  FileID := PDF.AddEmbeddedFile('C:\reports\sales.csv', 'text/csv');
  if FileID = 0 then Exit;

  PDF.AddFileAttachment('Source data', FileID);

  PDF.AddPage;
  PDF.PrintText(50, 750, 'See attached source data');
  PDF.AddLinkToEmbeddedFile(50, 720, 16, 16, FileID, 'Source data', 'Open source CSV', 4, 0);

  PDF.SaveToFile('with-attachment.pdf');
end;