기술 문서

Delphi의 PDF/A-3 연관 파일과 AFRelationship

Delphi에서 PDF/A-3 문서에 소스 파일을 첨부하려면, PDFium Component는 PDF 2.0 associated-file 체인을 기록합니다. MIME /Subtype을 실은 임베디드 파일 스트림, /AFRelationship을 지닌 파일 명세, 그리고 카탈로그나 페이지에 걸린 /AF 배열입니다. InjectAssociateFiles와 TPdf.SaveAsWithAssociateFiles는 그 체인을 한 번의 증분 업데이트로 만들고, MIME 타입은 올바르게 이스케이프된 PDF 이름 하나로 직렬화됩니다. 이 글의 나머지는 검증기가 무엇을 검사하는지, text/plain을 부수는 한 글자짜리 함정, 그리고 오타나 읽을 수 없는 trailer가 엉뚱한 파일을 만들지 못하게 막는 검사들을 다룹니다

PDF/A-3 associated file에는 실제로 무엇이 필요할까요?

PDF/A-3 첨부 파일은 세 개체가 서로 합의할 때만 검증을 통과합니다. 임베디드 파일 스트림이 /Type /EmbeddedFile과 MIME /Subtype을 선언하고, 파일 명세 사전(ISO 32000-2 §7.11.3)이 /F, /UF, /EF, /AFRelationship을 지니며, 문서 안의 무언가가 그 파일 명세를 /AF 배열(ISO 32000-2 §14.13)로 참조합니다. TPdf.CreateAttachment가 하는 것처럼 /Names /EmbeddedFiles 트리를 통한 평범한 임베딩은 연관 필드를 전혀 설정하지 않습니다. PDF/A-3b 검증 실행이 이 의존성을 구체적으로 보여 줍니다. /AFRelationship 키만 바꾸면 파일은 ISO 19005-3 절 6.8의 정확히 한 규칙에서 떨어지고, MIME /Subtype만 빼면 다른 6.8 규칙이 떨어지며, 같은 첨부를 PDF/A-1b 후보에 넣으면 메타데이터가 얼마나 말쑥하든 그대로 거부됩니다. PDF/A-1은 임베디드 파일을 금지하니까요

PDFium Component에서 PDF/A-3 associated file의 세 개체 체인: application xml 같은 MIME Subtype을 실은 EmbeddedFile 스트림, F, UF, EF와 Data로 설정된 AFRelationship을 지닌 파일 명세, 그리고 카탈로그나 페이지에서 오는 그것을 위한 AF 배열. ISO 19005-3 절 6.8이 통과하기 전에 검증기가 검사하는 세 개체입니다
스트림, 파일 명세, AF 배열은 서로 합의해야 합니다. TPdf.CreateAttachment의 평범한 이름 트리 임베딩은 설계상 연관 필드를 설정하지 않습니다

relationship 값은 사람들이 감으로 추측하는 부분입니다. FPdfAssocFiles의 TPdfAFRelationship은 인젝터가 내보낼 수 있는 각 이름 토큰에 열거 멤버를 하나씩 매핑하는데, 처음 다섯만 ISO 19005-3이 인식하는 부분집합에 속합니다:

  • afSource → /Source: 워드프로세서 파일이나 스프레드시트처럼 PDF가 만들어진 원본
  • afData → /Data: 보이는 콘텐츠가 파생되었거나 표현하는 기계 판독 가능 데이터
  • afAlternative → /Alternative, afSupplement → /Supplement, afUnspecified → /Unspecified
  • afEncryptedPayload, afFormData, afTemplate: PDF/A-3 부분집합 밖에 있는 PDF 2.0 추가분이므로 아카이브 출력에는 넣지 마세요

/Subtype /text/plain은 왜 검증을 깨뜨릴까?

준수 간극이 아니라 토크나이즈 오류입니다. 호출자의 문자열을 슬래시 뒤에 곧바로 이어 붙이면 /Subtype /text/plain이 됩니다. PDF 문법에서 두 번째 슬래시는 새 name 개체(ISO 32000-1 §7.3.5)를 시작하므로, 스트림 사전은 갑자기 키 /Subtype, 이름 /text, 그리고 키-값 쌍의 균형을 깨뜨리는 매달린 이름 /plain을 담게 됩니다. 독립 PDF/A 검증기는 EmbeddedFile 사전을 파싱하다가, 즉 PDF/A 규칙에 도달하기도 전에 파일을 거부하고, 그래서 실패는 빠진 첨부 속성처럼이 아니라 파일 손상처럼 보입니다

PDFium Component는 MIME 값을 EscapePdfName으로 보내 /text#2Fplain을 내놓습니다. 디코딩하면 text/plain인 이름 하나입니다. 이스케이핑은 일부러 슬래시보다 넓습니다. 32 이하의 모든 바이트(공백, 탭, CR, LF), 127 이상의 모든 바이트, 구분자 ()<>[]{}/%, 그리고 # 이스케이프 문자 자체가 #XX가 됩니다. 슬래시만 이스케이프하면 다른 구멍이 남습니다. >>나 공백을 담은 MIME 문자열은 사전을 일찍 닫거나 추가 키를 주입할 수 있습니다

PDFium Component에서 MIME subtype text/plain이 PDF/A-3 파싱을 깨뜨리는 이유: 값을 슬래시 뒤에 이어 붙이면 name 개체 두 개가 생깁니다. 값인 /text와 EmbeddedFile 사전의 균형을 깨뜨리는 매달린 /plain이요. EscapePdfName은 값을 /text#2Fplain으로 써 text/plain으로 디코딩되는 이름 하나로 만듭니다
실패는 파일 손상처럼 보였습니다. 파서에서, 즉 어떤 PDF/A 규칙보다도 앞서 일어났기 때문입니다. 이스케이프된 이름은 쌍의 균형과 검증기의 읽기를 지켜 줍니다
// MIMEType = 'text/plain'일 때
//   순진한 이어 붙이기:  /Type /EmbeddedFile /Subtype /text/plain     (이름 두 개)
//   인젝터 출력:      /Type /EmbeddedFile /Subtype /text#2Fplain   (이름 하나)
//
// 호출자는 언제나 평범한 MIME 값을 넘깁니다. 미리 직접 이스케이프하면
// '#'가 이중 인코딩되어 'text#2Fplain'이 'text#232Fplain'이 됩니다
Options.Files[0].MIMEType := 'text/plain';

InjectAssociateFiles로 PDF/A-3 파일 만들기

PDF/A-3 출력을 위해서는 TPdf.SaveAsPdfAToStream으로 준수하는 기본 문서를 만든 다음 그 스트림에 InjectAssociateFiles를 호출하세요. PDF/A-3b 검증을 통과하는 것은 이 두 단계 파이프라인입니다. TPdf.SaveAsWithAssociateFiles는 편의 래퍼지만, PDF/A 작성기가 아니라 saRemoveSecurity를 붙인 평범한 SaveAs 경로로 저장하므로 PDF/A가 요구하는 XMP 식별과 출력 인텐트를 추가하지 않습니다. 레코드 타입은 FPdfAssocFiles와 FPdfPdfa에 살므로 두 유닛 모두 uses 절에 들어가야 합니다. FileName과 Description은 평범한 ASCII에 국한되지 않습니다. /UF와 /Desc는 PDF 텍스트 문자열로 기록됩니다. 인쇄 가능 ASCII는 문자 그대로, 나머지는 바이트 순서 표식과 함께 UTF-16BE로요. 반면 레거시 /F 이름은 항상 이식 가능한 인쇄 가능 ASCII로, 다른 모든 문자는 _로 바뀝니다. /F를 자기 코드 페이지로 디코딩하는 리더는 깨진 글자 대신 밑줄을 보게 됩니다

uses
  System.SysUtils, System.Classes, System.IOUtils,
  PDFium, FPdfPdfa, FPdfAssocFiles;

procedure SaveWithSourceData(Pdf: TPdf; const XmlPath, OutPath: string);
var
  PdfAOptions: TPdfASaveOptions;
  Options: TAssocFilesOptions;
  Base: TMemoryStream;
  Output: TFileStream;
begin
  PdfAOptions := TPdfASaveOptions.Default;
  PdfAOptions.Conformance := pac3b;

  Options := TAssocFilesOptions.Default;      // TargetPage = 0: 카탈로그 수준 /AF
  SetLength(Options.Files, 1);
  Options.Files[0].FileName := 'invoice-data.xml';
  Options.Files[0].Description := 'Structured invoice data';
  Options.Files[0].Content := TFile.ReadAllBytes(XmlPath);
  Options.Files[0].Relationship := afData;
  Options.Files[0].MIMEType := 'application/xml';  // /application#2Fxml로 기록됩니다

  Base := TMemoryStream.Create;
  try
    if not Pdf.SaveAsPdfAToStream(Base, PdfAOptions) then
      raise Exception.Create('PDF/A-3 base save failed');
    Output := TFileStream.Create(OutPath, fmCreate);
    try
      InjectAssociateFiles(Base, Output, Options);  // Base를 되감습니다. 실패 시 EPdfAssocFilesError
    finally
      Output.Free;
    end;
  finally
    Base.Free;
  end;
end;

카탈로그인가 페이지인가: /AF 배열은 어디에 놓일까요?

TAssocFilesOptions.TargetPage가 /AF 배열의 소유자를 결정합니다. 0이면 카탈로그에 문서 수준 연관으로 붙고, 1..N이면 그 페이지 사전에 붙습니다(1 기반). 인젝터는 고정 레이아웃의 단일 증분 업데이트로 모든 것을 추가합니다(임베디드 스트림, 그다음 파일 명세들, 그다음 /AF 배열, 그다음 다시 쓴 카탈로그나 페이지 개체). 기존 개체는 오프셋을 유지하고 아무것도 재압축되지 않습니다. 대상 사전에 있던 기존 /AF 항목은 병합이 아니라 교체되므로 반복 저장은 멱등하지만, 다른 파일 목록으로 두 번째 호출하면 그쪽이 이깁니다. TargetPage는 엄격히 검사됩니다. SaveAsWithAssociateFiles와 SaveAsWithAssociateFilesToStream은 TargetPage가 0..PageCount 밖이면 EPdfError를 일으키고, InjectAssociateFiles는 음의 TargetPage나 존재하지 않는 페이지를 가리키는 값에 대해 EPdfAssocFilesError를 일으키며 대상 스트림은 그대로 둡니다. 오타가 조용히 페이지 수준 연관을 문서 수준으로 바꿀 수 없다는 뜻입니다. TargetPage는 문서 페이지 순서에서 그 위치의 페이지를 가리킵니다. 여러분 코드에서 피할 함정은 저장된 바이트를 파일 순서로 훑으며 /Type /Page 사전을 찾는 것입니다. 페이지가 재정렬되거나 삽입되고 나면 페이지 개체가 표시 순서와 다르게 저장될 수 있고, 파일은 다른 페이지에 붙습니다

PDFium Component에서 AF 배열이 놓이는 곳: TargetPage가 0이면 카탈로그에, 페이지 1부터 N까지는 그 페이지 사전에 붙고, 범위 밖 값은 예외를 일으킵니다. 인젝터는 모든 것을 기존 오프셋을 유지하는 고정 레이아웃의 단일 증분 업데이트로 추가하며 기존 AF 항목은 교체합니다
범위 밖 TargetPage는 조용히 문서 수준 연관이 되는 대신 예외를 일으키고, 다른 파일 목록으로 두 번째 호출하면 여전히 그쪽이 이깁니다
procedure AttachChartSource(Pdf: TPdf; PageNumber: Integer;
  const CsvBytes: TBytes; const OutPath: string);
var
  Options: TAssocFilesOptions;
begin
  // 범위 밖 TargetPage는 EPdfError를 일으킨다. 미리 검사하면
  // 오류 메시지가 페이지를 이름으로 짚어 준다
  if (PageNumber < 1) or (PageNumber > Pdf.PageCount) then
    raise EArgumentOutOfRangeException.CreateFmt('No page %d', [PageNumber]);

  Options := TAssocFilesOptions.Default;
  Options.TargetPage := PageNumber;
  SetLength(Options.Files, 1);
  Options.Files[0].FileName := 'chart-data.csv';
  Options.Files[0].Content := CsvBytes;
  Options.Files[0].Relationship := afSource;
  Options.Files[0].MIMEType := 'text/csv';

  if not Pdf.SaveAsWithAssociateFiles(OutPath, Options) then
    raise Exception.Create('Associated-file save failed');
end;

AFRelationship을 확실하게 되읽으려면 어떻게 할까요?

TPdf.AttachmentRelationship[Index]는 네이티브 FPDFAttachment_GetAFRelationship 익스포트를 통해 첨부의 /AFRelationship 이름을 반환하지만, 빈 문자열은 두 가지 의미가 가능하므로 먼저 AttachmentRelationshipFeaturesAvailable을 호출하세요. 바인딩은 관대하게 로드됩니다. PDFium DLL에 그 익스포트가 없으면 모든 relationship이 빈 문자열로 읽히는데, 이는 단순히 /AFRelationship이 없는 파일 명세와 구별되지 않습니다. 이 속성은 /Names /EmbeddedFiles 트리의 항목을 세는 AttachmentCount와 인덱스를 공유합니다. 인젝터는 /AF 체인만 쓰고 이름 트리 항목은 추가하지 않으므로, InjectAssociateFiles로 첨부된 파일은 그 인덱스 밖에 있습니다. 주입된 체인을 확인하려면 저장된 바이트를 검사하거나 PDF/A 검증기를 돌리세요. 그 이름 트리의 내부는 PDFium Component로 Delphi에서 PDF 첨부 파일 다루기에서 다룹니다

procedure ReportRelationships(const FileName: string);
var
  Pdf: TPdf;
  I: Integer;
  Rel: string;
begin
  if not AttachmentRelationshipFeaturesAvailable then
  begin
    Writeln('This PDFium build cannot report /AFRelationship');
    Exit;  // 빈 답은 모호하므로 묻지 않습니다
  end;

  Pdf := TPdf.Create(nil);
  try
    Pdf.FileName := FileName;
    Pdf.Active := True;
    for I := 0 to Pdf.AttachmentCount - 1 do
    begin
      Rel := Pdf.AttachmentRelationship[I];
      if Rel = '' then
        Rel := '(no /AFRelationship)';
      Writeln(Pdf.AttachmentName[I], ': ', Rel);
    end;
  finally
    Pdf.Free;
  end;
end;

SaveAsWithAssociateFiles가 보장하지 않는 것은?

TPdf.SaveAsWithAssociateFiles가 보장하는 것은 파일 형식 봉투와 요청한 파일이 주입됐다는 것이지 준수가 아닙니다. 저장된 바이트에 읽을 수 있는 trailer가 없거나 카탈로그 사전을 찾지 못하면, InjectAssociateFiles는 무엇을 쓰기 전에 EPdfAssocFilesError를 일으키고 SaveAsWithAssociateFiles는 False를 반환합니다. 메서드는 대상을 열기 전에 save store에서 완전한 출력을 만들므로, 거부되거나 실패한 저장은 기존 파일을 온전히 둡니다. 빈 Files 배열은 설계상 문서를 그대로 복사해 통과시킵니다. 페이로드의 내용도 여러분의 책임입니다. 인젝터는 XML 파일이 well-formed인지, MIME 타입이 바이트와 맞는지, 기본 문서가 애초에 PDF/A인지 검사하지 않습니다. 검증기가 보기 전까지는 최종 파일을 미검증으로 취급하세요. PDFium Component와 PDF/A 아카이브 준수가 묘사하는 것과 같은 규율입니다. 들어오는 사전을 직접 파싱한다면 같은 #XX 이름 규칙이 반대 방향으로도 적용되는데, 이는 PDF 사전을 파싱할 때의 name 토큰 함정에서 다루는 주제입니다

associated file, PDF/A 출력, 첨부 메타데이터와 검증은 모두 같은 컴포넌트에 실려 나오므로, 위의 파이프라인은 빌드에 두 번째 PDF 라이브러리 없이 돌아갑니다. API 레퍼런스, 평가판 다운로드와 라이선스 옵션은 PDFium Component 제품 페이지에 있습니다