EmbedFileA

Propriedades do documento

Descrição

O A final 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 cadeia são interpretados utilizando a página de códigos atual de SetAnsiMode

Incorpora um ficheiro externo no PDF e regista-o como anexo ao nível do documento. O Acrobat e outros leitores mostram os anexos ao nível do documento no respetivo painel lateral Anexos. A chamada é uma forma abreviada de AddEmbeddedFile seguida de AddToFileList: o ficheiro é armazenado como um fluxo de ficheiro incorporado e é adicionada à árvore de nomes /Names /EmbeddedFiles do Catálogo uma entrada que o referencia sob o título fornecido

Comportamento da versão PDF: os fluxos de ficheiros incorporados e os dicionários de especificação de ficheiros exigem PDF 1.3, enquanto a árvore de nomes /Names /EmbeddedFiles ao nível do documento utilizada por esta chamada de conveniência exige PDF 1.4. Se a versão atual do documento for inferior e a versão de gravação não estiver bloqueada, EmbedFile eleva automaticamente o documento para PDF 1.4 e regista /EmbeddedFiles name tree em AutoBumpedFeatures. Se o invocador bloquear uma versão de gravação inferior, a barreira de compatibilidade rejeita a gravação 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 apresentação mostrado no painel de anexos do leitor e utilizado como chave na árvore de nomes `/EmbeddedFiles`. Tem de ser exclusivo no documento; se já existir um ficheiro com este título, a chamada falha
FileName	O caminho completo do ficheiro de origem no disco. Os bytes deste ficheiro são copiados para o PDF
MIMEType	Tipo MIME que identifica o conteúdo do ficheiro (por exemplo, `image/jpeg`, `text/csv`, `application/xml`). Passe uma cadeia vazia quando o tipo MIME for desconhecido; os visualizadores recorrem à extensão do ficheiro

Valores devolvidos

0	Não foi possível incorporar o ficheiro — o ficheiro de origem está em falta, o título já é utilizado ou nenhum documento está aberto
1	O ficheiro foi incorporado e incluído na árvore de nomes dos anexos do documento

Observações

Esta chamada só cria um anexo ao nível do documento. Para desenhar numa página específica uma anotação de clipe clicável que aponte para o ficheiro incorporado, utilize AddEmbeddedFile seguido de AddFileAttachment (ou AddLinkToEmbeddedFile)

Compatibilidade PDF/A:

PDF/A-1 e PDF/A-2 (modos 1–4 de SetPDFAMode) proíbem ficheiros incorporados arbitrários. A proteção PDF/A bloqueia EmbedFile nesses modos
O PDF/A-3 (modos 5, 6 e 7) permite ficheiros incorporados de qualquer tipo MIME. A ISO 19005-3 também exige que todos os ficheiros incorporados declarem a sua relação com o documento através da chave AFRelationship — defina-a explicitamente com SetEmbeddedFileAFRelationship

Quando SetPDFUAMode está ativo, a biblioteca escreve automaticamente AFRelationship=Unspecified para qualquer ficheiro incorporado sem relação explícita; substitua-o com SetEmbeddedFileAFRelationship para cumprir a norma 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');

Consulte também

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode