EmbedFile

Propriedades do documento

Descrição

Embute um arquivo externo dentro do PDF e o registra como anexo de nível de documento. O Acrobat e outros readers mostram anexos de nível de documento no painel lateral Attachments. A chamada é um atalho para AddEmbeddedFile seguido de AddToFileList: o arquivo é armazenado como um embedded file stream e uma entrada que o referencia é adicionada à name tree /Names /EmbeddedFiles do Catalog sob o título informado.

Comportamento de versão do PDF: embedded file streams e dicionários de especificação de arquivo exigem PDF 1.3, enquanto a name tree /Names /EmbeddedFiles de nível de documento usada por esta chamada de conveniência exige PDF 1.4. Se a versão atual do documento for menor e a versão de salvamento não estiver travada, EmbedFile eleva automaticamente o documento para PDF 1.4 e registra /EmbeddedFiles name tree em AutoBumpedFeatures. Se o chamador travar uma versão de salvamento menor, o gate de compatibilidade rejeita o salvamento com LastErrorCode 602.

Sintaxe

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

Parâmetros

Title	O nome de exibição mostrado no painel de anexos do reader e usado como chave na name tree `/EmbeddedFiles`. Deve ser único no documento; se já existir um arquivo com esse título, a chamada falha.
FileName	O caminho completo do arquivo de origem no disco. Os bytes desse arquivo são copiados para o PDF.
MIMEType	Tipo MIME que identifica o conteúdo do arquivo (por exemplo, `image/jpeg`, `text/csv`, `application/xml`) Passe uma string vazia quando o tipo MIME for desconhecido; os visualizadores recorrerão à extensão do arquivo

Valores retornados

0	Não foi possível embutir o arquivo — o arquivo de origem não existe, o título já está em uso ou não há documento aberto.
1	O arquivo foi embutido e listado na name tree de anexos do documento.

Observações

Esta chamada só cria um anexo de nível de documento. Para desenhar uma anotação clicável de clipe de papel em uma página específica apontando para o arquivo embutido, use AddEmbeddedFile seguido de AddFileAttachment (ou AddLinkToEmbeddedFile).

PDF/A compatibility:

PDF/A-1 e PDF/A-2 (modos 1–4 de SetPDFAMode) proíbem arquivos embutidos arbitrários. A guarda do PDF/A bloqueia EmbedFile nesses modos.
O PDF/A-3 (modos 5, 6 e 7) permite arquivos embutidos de qualquer tipo MIME. A ISO 19005-3 também exige que todo arquivo embutido declare seu relacionamento com o documento pela chave AFRelationship — defina-a explicitamente com SetEmbeddedFileAFRelationship.

Quando SetPDFUAMode está ativo, a biblioteca grava AFRelationship=Unspecified automaticamente para todo arquivo embutido sem relacionamento explícito; sobrescreva com SetEmbeddedFileAFRelationship para satisfazer a ISO 14289-1 §7.11.

Exemplo

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

Veja também

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode