EmbedFile

문서 속성

설명

외부 파일을 PDF에 포함하고 문서 수준 첨부로 등록합니다. Acrobat과 다른 리더는 Attachments 측면 패널에 표시합니다. 이 호출은 AddEmbeddedFile 다음에 AddToFileList를 호출하는 축약형입니다. 파일을 포함 파일 스트림으로 저장하고 이를 참조하는 항목을 제공한 제목 아래 Catalog의 /Names /EmbeddedFiles 이름 트리에 추가합니다

PDF 버전 동작: 포함 파일 스트림과 파일 사양 사전에는 PDF 1.3이 필요하지만 이 편의 호출에서 사용하는 문서 수준 /Names /EmbeddedFiles 이름 트리에는 PDF 1.4가 필요합니다. 현재 문서 버전이 더 낮고 저장 버전이 잠기지 않은 경우 EmbedFile은 문서를 PDF 1.4로 자동 상승시키고 /EmbeddedFiles name tree를 AutoBumpedFeatures에 기록합니다. 호출자가 더 낮은 저장 버전을 잠그면 호환성 게이트가 LastErrorCode 602와 함께 저장을 거부합니다

구문

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

매개변수

Title	리더의 첨부 파일 패널에 표시되고 `/EmbeddedFiles` 이름 트리의 키로 사용하는 표시 이름입니다. 문서 안에서 고유해야 하며 같은 제목의 파일이 이미 있으면 호출이 실패합니다
FileName	디스크에 있는 소스 파일의 전체 경로입니다. 이 파일의 바이트가 PDF에 복사됩니다
MIMEType	파일 콘텐츠를 식별하는 MIME 형식입니다(예: `image/jpeg`, `text/csv`, `application/xml`). MIME 형식을 알 수 없으면 빈 문자열을 전달하며, 뷰어는 파일 확장자를 대신 사용합니다

반환 값

0	원본 파일이 없거나, 제목이 이미 사용 중이거나, 열린 문서가 없어 파일을 임베드할 수 없습니다
1	파일이 내장되고 문서 첨부 파일 이름 트리에 나열되었습니다

비고

이 호출은 문서 수준 첨부 파일만 만듭니다. 특정 페이지에 포함 파일을 가리키는 클릭 가능한 종이 클립 주석을 그리려면 대신 AddEmbeddedFile 뒤에 AddFileAttachment 또는 AddLinkToEmbeddedFile을 사용합니다

PDF/A 호환성:

PDF/A-1과 PDF/A-2(SetPDFAMode의 모드 1–4)는 임의 포함 파일을 금지합니다. PDF/A 보호가 해당 모드에서 EmbedFile을 차단합니다
PDF/A-3(모드 5, 6 및 7)은 모든 MIME 형식의 포함 파일을 허용합니다. ISO 19005-3은 각 포함 파일이 AFRelationship 키를 통해 문서와의 관계를 선언하도록 요구합니다. SetEmbeddedFileAFRelationship로 명시적으로 설정합니다

SetPDFUAMode가 활성 상태이면 명시적 관계가 없는 모든 포함 파일에 대해 라이브러리가 AFRelationship=Unspecified를 자동으로 씁니다. ISO 14289-1 §7.11을 충족하려면 SetEmbeddedFileAFRelationship로 재정의합니다

예제

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

참고 항목

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode