AddEmbeddedFile

Document properties

Description

Embeds a file inside the PDF as an embedded file stream but does not, by itself, register the file in any catalog list or draw a clickable annotation. The function returns an EmbeddedFileID handle that can be passed to AddFileAttachment (to attach a paper-clip icon on a page) or AddLinkToEmbeddedFile (to create a clickable hotspot that opens the file). To both embed a file and list it as a document-level attachment in a single call, use EmbedFile instead.

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, wchar_t * FileName, wchar_t * MIMEType);

Parameters

FileName	The full path and name of the source file on disk. Its bytes are copied verbatim into a PDF embedded file stream.
MIMEType	The MIME type of the file, for example `image/jpeg` or `application/xml`. May be an empty string when the MIME type is unknown.

Return values

0	The file could not be opened or no document is active.
Non-zero	An EmbeddedFileID handle for use with AddFileAttachment, AddLinkToEmbeddedFile, or 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.

A file embedded with AddEmbeddedFile alone is part of the PDF but invisible to the reader UI until it is registered in the document attachment list or referenced by a page annotation. Re-using the same EmbeddedFileID with AddFileAttachment and AddLinkToEmbeddedFile lets you expose one embedded file through both document-level and page-level UI without duplicating the embedded bytes.

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 and 6) — 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;