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, const wchar_t * FileName, const 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.

Yalnızca AddEmbeddedFile ile gömülen bir dosya PDF'in bir parçasıdır ancak belge eki listesine kaydedilene veya bir sayfa ek açıklaması tarafından başvurulana kadar okuyucu arayüzünde görünmez; aynı EmbeddedFileID'yi AddFileAttachment ve AddLinkToEmbeddedFile ile yeniden kullanmak, gömülü baytları çoğaltmadan tek bir gömülü dosyayı hem belge düzeyindeki hem de sayfa düzeyindeki arayüz aracılığıyla sunmanıza olanak tanır

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;