EmbedFileA

Propriedades do documento

Descrição

O sufixo A indica o ponto de entrada ANSI (char) da DLL; a superfície ActiveX/COM expõe apenas a forma Unicode. O comportamento é idêntico ao de EmbedFile e os argumentos de string são interpretados usando a página de código atual definida por SetAnsiMode

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

DLL

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