EmbedFile

Document properties

Description

Embeds an external file inside the PDF and registers it as a document-level attachment. Acrobat and other readers show document-level attachments in their Attachments side panel. The call is shorthand for AddEmbeddedFile followed by AddToFileList: the file is stored as an embedded file stream, and an entry referencing it is added to the Catalog's /Names /EmbeddedFiles name tree under the supplied title.

PDF version behavior: embedded file streams and file specification dictionaries require PDF 1.3, while the document-level /Names /EmbeddedFiles name tree used by this convenience call requires PDF 1.4. If the current document version is lower and the save version is not locked, EmbedFile automatically raises the document to PDF 1.4 and records /EmbeddedFiles name tree in AutoBumpedFeatures. If the caller locks a lower save version, the compatibility gate rejects the save with LastErrorCode 602.

Syntax

Delphi

function TPDFlib.EmbedFile(const Title, FileName, MIMEType: WideString): Integer;

ActiveX

Function PDFlib::EmbedFile(Title As String, FileName As String, MIMEType As String) As Long

DLL

int DLEmbedFile(int InstanceID, wchar_t * Title, wchar_t * FileName, wchar_t * MIMEType);

Parameters

Title	The display name shown in the reader's attachments panel and used as the key in the `/EmbeddedFiles` name tree. Must be unique within the document; if a file with this title already exists the call fails.
FileName	The full path of the source file on disk. The bytes of this file are copied into the PDF.
MIMEType	MIME type identifying the file's content (for example `image/jpeg`, `text/csv`, `application/xml`). Pass an empty string when the MIME type is unknown; viewers will fall back to the file extension.

Return values

0	The file could not be embedded — the source file is missing, the title is already used, or no document is open.
1	The file was embedded and listed in the document attachments name tree.

Remarks

This call only creates a document-level attachment. To draw a clickable paper-clip annotation on a specific page that points at the embedded file, use AddEmbeddedFile followed by AddFileAttachment (or AddLinkToEmbeddedFile) instead.

PDF/A compatibility:

PDF/A-1, PDF/A-2 (modes 1–4 of SetPDFAMode) forbid arbitrary embedded files. The PDF/A guard blocks EmbedFile in those modes.
PDF/A-3 (modes 5 and 6) permits embedded files of any MIME type. ISO 19005-3 also requires every embedded file to declare its relationship to the document via the AFRelationship key — set it explicitly with SetEmbeddedFileAFRelationship.

When SetPDFUAMode is active the library writes AFRelationship=Unspecified automatically for any embedded file that has no explicit relationship; override it with SetEmbeddedFileAFRelationship to satisfy ISO 14289-1 §7.11.

Example

// 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');