EmbedFileA

Proprietà del documento

Descrizione

Il suffisso A indica l'entry point DLL ANSI (char); l'interfaccia ActiveX/COM espone soltanto la forma Unicode. Il comportamento è identico a EmbedFile e gli argomenti stringa vengono interpretati usando la code page corrente di SetAnsiMode

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 DLEmbedFileA(InstanceID: Integer; Title, FileName, MIMEType: PAnsiChar): Integer;

DLL

int DLEmbedFileA(int InstanceID, const char * Title, const char * FileName, const char * 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