EmbedFile

Proprietà del documento

Descrizione

Incorpora un file esterno nel PDF e lo registra come allegato a livello di documento. Acrobat e altri lettori mostrano gli allegati a livello di documento nel relativo riquadro laterale Attachments. La chiamata è una forma abbreviata di AddEmbeddedFile seguita da AddToFileList: il file viene memorizzato come flusso di file incorporato e una voce che vi fa riferimento viene aggiunta all'albero dei nomi /Names /EmbeddedFiles del Catalog con il titolo fornito

I flussi incorporati richiedono PDF 1.3, mentre l'albero /Names /EmbeddedFiles richiede PDF 1.4. Se possibile, EmbedFile passa automaticamente a PDF 1.4 e registra /EmbeddedFiles name tree in AutoBumpedFeatures; una versione precedente bloccata fallisce con LastErrorCode 602

Sintassi

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

Parametri

Title	Nome visualizzato nel pannello allegati e chiave nell'albero `/EmbeddedFiles`. Deve essere univoco; un titolo già esistente causa errore
FileName	Percorso completo del file di origine su disco. I byte di questo file vengono copiati nel PDF
MIMEType	Tipo MIME che identifica il contenuto del file, ad esempio `image/jpeg`, `text/csv` o `application/xml`. Passare una stringa vuota quando il tipo MIME è sconosciuto; i visualizzatori useranno come ripiego l'estensione del file

Valori restituiti

0	Impossibile incorporare il file — origine mancante, titolo già usato o nessun documento aperto
1	Il file è stato incorporato e inserito nell'albero dei nomi degli allegati del documento

Note

Questa chiamata crea soltanto un allegato a livello di documento. Per disegnare su una pagina specifica un'annotazione a graffetta selezionabile che punti al file incorporato, usare invece AddEmbeddedFile seguito da AddFileAttachment, oppure AddLinkToEmbeddedFile

Compatibilità PDF/A:

PDF/A-1 e PDF/A-2 (modalità 1–4 di SetPDFAMode) vietano file incorporati arbitrari. La protezione blocca EmbedFile.
PDF/A-3 consente file incorporati di qualsiasi MIME. ISO 19005-3 richiede la relazione AFRelationship, da impostare con SetEmbeddedFileAFRelationship

Quando SetPDFUAMode è attivo, la libreria scrive automaticamente AFRelationship=Unspecified per ogni file incorporato privo di una relazione esplicita; è possibile sostituirlo con SetEmbeddedFileAFRelationship per soddisfare ISO 14289-1 §7.11

Esempio

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

Vedere anche

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode