AddEmbeddedFile

Document properties

Description

Incorpora un file all'interno del PDF come stream di file incorporato ma, di per sé, non registra il file in alcun elenco del catalogo né disegna un'annotazione cliccabile; la funzione restituisce un handle EmbeddedFileID che può essere passato a AddFileAttachment (per allegare un'icona a forma di graffetta su una pagina) o a AddLinkToEmbeddedFile (per creare un hotspot cliccabile che opzione il file); per incorporare ed elencare un file come allegato a livello di documento in una singola chiamata, usare invece EmbedFile

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	Il percorso completo e il nome del file di origine su disco; i suoi byte vengono copiati letteralmente in uno stream di file incorporato PDF
MIMEType	Il tipo MIME del file, ad esempio `image/jpeg` o `application/xml`; può essere una stringa vuota quando il tipo MIME è sconosciuto

Return values

0	Impossibile aprire il file o nessun documento è attivo
Non-zero	Un gestore EmbeddedFileID da utilizzare con AddFileAttachment, AddLinkToEmbeddedFile o SetEmbeddedFileStrProperty

Remarks

Comportamento della versione PDF: gli stream di file incorporati e i dizionari delle specifiche dei file richiedono PDF 1.3; se la versione corrente del documento è inferiore e la versione di salvataggio non è bloccata, AddEmbeddedFile eleva automaticamente il documento a PDF 1.3; le chiamate che registrano il file come allegato a livello di documento possono richiedere una versione superiore: AddFileAttachment e EmbedFile utilizzano l'albero dei nomi PDF 1.4 /Names /EmbeddedFiles, mentre AddLinkToEmbeddedFile utilizza la trasparenza dell'aspetto/opacità dell'annotazione PDF 1.4

Un file incorporato solo con AddEmbeddedFile fa parte del PDF ma è invisibile all'interfaccia utente del lettore finché non viene registrato nell'elenco degli allegati del documento o referenziato da un'annotazione di pagina; riutilizzare lo stesso EmbeddedFileID con AddFileAttachment e AddLinkToEmbeddedFile consente di esporre un singolo file incorporato sia tramite l'interfaccia utente a livello di documento che a livello di pagina senza duplicare i byte incorporati

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;