THPDFHeadlessDocument

HPDFHeadlessDocument는 기존 HotPDF 객체 파서, Direct File 헬퍼, 폰트 디코더, 콘텐츠 인터프리터, 필터 디코더, xref 라이터를 써서 네이티브 Linux와 Windows용 콘솔 문서 API를 제공합니다

문서 로더는 클래식 교차 참조 테이블, xref 스트림, 하이브리드 xref 섹션, 증분 Prev 체인, 다이렉트·압축 객체, 상속 페이지 리소스, 콘텐츠 배열, Form XObject, AcroForm 필드 트리를 받습니다

하이브리드 사이드 스트림은 동봉된 테이블보다 우선하고 더 새 리비전이 오래된 것보다 우선합니다. 객체 스트림 멤버는 공유 객체 파서로 지연 디코딩·파싱됩니다

라이프사이클과 소유권

Create는 THPDFHeadlessDocumentOptions.Default를 쓰고, 옵션 오버로드는 명시적 예산과 호출자 소유 취소 토큰을 받습니다

LoadFromFile은 이전 문서를 닫고 소스를 읽기 전용으로 열어 현재 객체 그래프를 로드하며, 실패하면 부분 상태를 닫습니다. Close는 소스와 로드된 모든 객체를 해제합니다

LoadFromFile(FileName, Password)는 THPDFHeadlessAES256Security로 Standard AES-256 R5 또는 R6 문서를 인증하고, 기존 인자 하나짜리 오버로드는 빈 비밀번호를 씁니다

사용자 비밀번호는 텍스트 추출이나 폼 채우기 연산 실행 전에 그 권한을 부여해야 하고, 소유자 비밀번호는 사용자 권한 제한을 우회합니다. 잘못된 비밀번호, 인증된 Perms 불일치, 거부된 연산, 형식이 틀린 암호 페이로드는 각각 별개의 문서 진단을 냅니다

다이렉트 문자열과 스트림은 공유 암호화 코드로 복호화되고, 압축 멤버는 컨테이너와 함께만 복호화되며, 암호화된 증분 교체는 원본 키와 권한 정책 아래 암호화된 채로 유지됩니다

비밀번호는 SASLprep 정규화 없이 127바이트에서 자른 UTF-8 바이트를 씁니다. 지원하지 않는 핸들러, 명시적 Crypt 필터, PDF MAC 정책은 무시하지 않고 진단합니다

인코딩된 사전 키와 리소스 이름은 쓰기 전에 디코딩되고 대소문자는 계속 구분되며, 중복된 디코딩 키는 거절됩니다. 필드 플래그와 MaxLen은 지원되는 음수가 아닌 32비트 범위 안이어야 합니다

인스턴스는 스레드 세이프하지 않습니다. 워커당 인스턴스 하나를 쓰고 인스턴스를 파괴할 때까지 취소 토큰을 살려 두세요

페이지와 텍스트

PageCount는 페이지 트리 리프 개수를 보고하고, ExtractPageText(PageIndex)는 0부터 시작하는 인덱스를 받아 공유 글리프 인터프리터로 조립한 Unicode 텍스트를 반환합니다

ExtractPageTextBounded는 텍스트 준비 전에 임시 글리프·스트림 한도를 적용하고 성공, 실패, 취소 뒤에는 원본 리소스 옵션을 모두 복원합니다

GetObjectAccess는 네이티브 구조·전체 비교를 위해 bounded 인덱스 할당과 함께 읽기 전용으로 빌린 catalog, information, 객체 접근을 노출합니다

텍스트 디코딩은 폰트 인코딩, 인코딩 차이, 임베드된 ToUnicode CMap, 명시적 너비, 표준 폰트 메트릭 프로바이더를 따릅니다. 중첩 Form XObject는 자체 행렬을 적용하고 자신의 또는 상속된 리소스 사전을 씁니다

Linux 표준 폰트 폴백에는 Fontconfig와 설치된 TrueType 폰트가 필요합니다. 복잡한 문서 폰트는 지원되는 디코딩 전략을 제공해야 하고, 폰트 리소스가 없으면 진단을 냅니다

AppendPageText는 원본 페이지 콘텐츠와 암호화 보안 정책을 유지하면서 보이는 또는 맞춰진 보이지 않는 Unicode 텍스트를 더합니다

AppendImportedPages는 기존 대상 리비전과 인증된 암호화 정책을 유지하면서 선택한 페이지 리소스 그래프, 상속 지오메트리, 보이는 normal appearance를 클론합니다

AcroForm 텍스트 값

FormFieldCount, GetFormField(FieldIndex), FindFormField(Name)은 완전 한정 이름과 상속된 필드 타입, 플래그, 최대 길이, 값으로 터미널 필드를 나열합니다. 인덱스는 0부터 시작하고 없는 이름은 -1을 반환합니다

SetTextFieldValue(FieldIndex, Text)는 쓰기 가능한 Tx 필드를 받고 UTF-16BE PDF 문자열을 기록하며 AcroForm 사전에 NeedAppearances=true를 설정합니다

값만 쓰는 이 메서드는 뷰어의 재생성에 의존합니다. appearance를 재생성하지 않는 뷰어는 예전 appearance나 빈 위젯을 계속 보여줄 수 있습니다

SetTextFieldValueWithAppearance는 호출자가 제공한 TrueType 폰트, 실제 글리프 메트릭, Identity-H 인코딩, ToUnicode, 전체 FontFile2 임베딩으로 기존 모든 위젯에 명시적 Unicode appearance를 생성합니다

appearance 프로필은 한 줄·여러 줄 텍스트, 줄바꿈, comb 셀, 90도 회전, 고정 크기 또는 자동 맞춤, 정렬, 선택적 네이티브 HarfBuzz/FriBidi 복합 셰이핑을 지원합니다

SetChoiceFieldValuesWithAppearance는 다중 선택 리스트 박스, 상속 옵션, 정렬된 익스포트 배열, 보이는 선택된 모든 행을 다룹니다. 단일 값 헬퍼도 combo 익스포트/표시 레이블을 지원합니다

GetChoiceFieldValues는 선택된 익스포트 배열 전체를 읽고, SetButtonFieldValueWithAppearance와 SetPushButtonAppearance는 실제 버튼 상태와 캡션을 생성합니다

새 appearance 객체와 스트림은 필드 변경 전에 상한이 검사되고 저장할 때 원본 AES 보안 정책 아래 암호화된 채로 유지됩니다. 네이티브 Linux Cairo와 독립 리더는 같은 생성된 객체를 소비합니다

읽기 전용 필드, UTF-16 코드 유닛 기준 MaxLen보다 긴 값, 텍스트가 아닌 필드, XFA 폼, 서명된 필드, certified 문서 권한은 편집이 거절됩니다

서명된 문서는 인증된 DocMDP와 FieldMDP 정책을 씁니다. 허용된 form 갱신은 기존 서명 리비전을 보존하고, 잠긴 필드, P1 제한, 서명된 signature 필드 덮어쓰기 시도는 거절됩니다

검증된 DSS/VRI 증거는 기존 ByteRange 서명을 바꾸지 않으면서 증분 리비전에 인증된 인증서·폐기 데이터를 더합니다

서명 검증

SignatureCount는 서명된 AcroForm 서명 필드를 나열하고 VerifySignature(SignatureIndex, Options)는 공유 파서와 스트리밍 OpenSSL 3 CMS 프로바이더로 0부터 시작하는 서명을 검증합니다

PDF 프로필은 hexadecimal 또는 표준 literal Contents를 가진 adbe.pkcs7.detached와 자동 인식되는 ETSI.CAdES.detached를 받습니다. CAdES는 항상 ESS signing-certificate 바인딩을 인증하고, 명시적 CA 설정은 신뢰를 따로 평가합니다

ETSI.RFC3161을 쓰는 DocTimeStamp는 실제 캡슐화된 TSTInfo, ESS, TSA 목적과 서명자 이름, 정확한 PDF 임프린트를 자동으로 인증합니다. 구성된 timestamp 루트와 CRL은 TSA 신뢰를 따로 평가합니다

검증은 구분자까지 포함한 미서명 구간을 정확히 확인하고 암호화 검증 전에 그 디코딩 바이트를 현재 서명 사전에 묶습니다

결과는 무결성, 명시적으로 평가한 CA 신뢰, 인증된 리비전 뒤의 미서명 바이트를 구분하고, 지원하지 않는 PDF 서명 프로필은 타입이 있는 진단을 냅니다

런타임 요구 사항은 HPDFVerifyHeadlessCMS를, 예산과 신뢰 설정은 THPDFHeadlessCMSOptions를 참고하세요

증분 승인 서명

SignToFile는 기존의 쓰기 가능하고 서명되지 않은 Sig 필드에 서명하고, 호출자가 제공한 PEM 인증서와 암호화하지 않은 PEM 개인 키로 독립적인 증분 갱신 PDF를 발행합니다

AddSignatureField는 단순 임포트 PDF에서 새 AcroForm을 만드는 것까지 포함해 페이지 위젯과 그 AcroForm 링크를 만들고, SetSignatureFieldAppearance는 보이는 캡션을 생성하며, SignPFXToFile는 체인을 포함한 PKCS12 인증서/키 아이덴티티를 로드합니다

CertificationPermission은 첫 DocMDP certification 서명을 만듭니다. P2와 P3는 기존 필드에서 이후 승인 서명을 허용하고, P1은 추가 서명을 거부합니다

원본 소스 바이트와 로드된 객체 그래프는 그대로입니다. 이후 승인 서명은 이전 서명 바이트와 인증된 리비전 경계를 보존합니다

Standard AES-256 R5·R6 암호화, 비밀번호, ID, 권한은 암호화된 객체 스트림 소스를 포함해 계속 적용됩니다. 서명 Contents 문자열은 PDF의 암호화 제외 규정을 따릅니다

기존 서명 값, 읽기 전용 필드, certified 문서 정책, 거부된 폼 채우기 권한, 어긋난 취소 토큰, 소진된 출력 예산은 출력을 발행하지 않고 거절됩니다

문서 타임스탬프

TimestampToFile는 애플리케이션 서명 키 없이 기존 미서명 서명 필드에 실제 RFC 3161 문서 타임스탬프를 만들며, 호출자 소유 TSA 전송과 명시적 TSA 신뢰를 씁니다

라이터는 원본 리비전과 AES 보안을 유지하고 PDF 2.0 이전 입력용 ESIC 확장을 선언하며, nonce, 임프린트, 서명, 인증서, 구성된 폐기, 시드 검사가 모두 지나야 원자적으로 발행합니다

필요한 인증된 문서 타임스탬프 변경은 DocMDP와 FieldMDP 아래에서 허용되고, 일반 폼 편집과 승인 서명은 원래 제한을 유지합니다

FDF와 XFDF 폼 교환

ExportAnnotationsFDF은 유계 주석 객체 그래프와 공유 appearance 리소스를 내보냅니다. SaveAnnotationsFDFToFile는 이름 있는 교체와 추가를 독립적인 원자적 PDF 리비전으로 준비합니다

바이너리 FDF 주석 프로파일은 인증된 문서의 암호화와 서명 정책, 컨텍스트 민감 로컬 GoTo 페이지 참조, 정확한 무변경 게시를 보존합니다. 성공과 실패 모두에서 로드된 문서를 그대로 둡니다

SaveAnnotationsXFDFToFile는 bounded 매핑 어노테이션을 독립적인 증분 리비전에 덧붙이고, HPDFExportHeadlessAnnotationsXFDF는 그 XFDF 바이트를 반환합니다

ExportFormData는 실제 choice 배열과 checkbox·radio 익스포트 상태를 포함한 bounded Unicode 필드 데이터를 반환합니다

ImportFormDataToFile는 비공개 인증 리비전 그래프에서 실제 appearance를 재생성하고 로드된 소스 상태를 유지하면서 증분 PDF를 원자적으로 발행합니다

ImportRichFormDataToFile는 FDF RV나 XFDF value-richtext에서 실제 regular, bold, italic, bold-italic 폰트 프로그램과 함께 bounded XHTML 프로필을 임포트합니다

SaveRichTextFieldUpdatesToFile는 scalar 필드와 원본 typed 리치 run을 하나의 독립 원자 리비전으로 적용하며 실제 폰트 프로그램과 PDF 수치 정밀도를 보존합니다. 바뀌지 않은 보호 필드는 모든 위젯에 대해 일치하는 디코딩 appearance와 해석된 리소스를 요구합니다

기존 암호화, 읽기 전용 플래그, 인증된 DocMDP·FieldMDP, 원본 서명, 취소와 리소스 예산은 계속 강제됩니다. 지원되는 문법과 scalar 교환 경계는 네이티브 FDF·XFDF 폼 데이터를 참고하세요

빌린 렌더링 접근

GetRenderAccess(PageIndex)는 THPDFHeadlessRenderAccess를 통해 기존 페이지 사전, 상속 리소스, 폰트 리졸버, 객체 해석, 권한 검사, 취소 토큰, bounded 디코딩 스트림 콜백을 제공합니다

이것은 직렬 읽기 전용 빌린 뷰입니다. 렌더러가 끝날 때까지 문서는 로드된 채 변경 없이 유지되어야 하고 호출자는 노출된 객체 그래프를 바꾸면 안 됩니다

뷰의 RequireOutputPath 콜백은 파일을 만들거나 수정하지 않고 예상 출력을 소스의 정규 경로와 물리 파일 신원과 대조합니다

독립 출력

ExtractPageGlyphs는 bounded 중첩 콘텐츠 워커로 위치가 정해진 글리프를 반환하고, AnalyzePageSemanticText는 네이티브 계약 비교에 쓸 의미 텍스트와 소스 지오메트리를 제공합니다

SaveToFile(FileName)은 원본 바이트를 복사하고 교체 객체 값, 클래식 xref 테이블, Prev로 연결된 트레일러를 덧붙입니다. 압축 객체 멤버는 덧붙인 리비전에서 다이렉트 객체로 실체화되고 원본 스트림 바이트는 보존됩니다

출력은 소스 경로나 파일 신원을 별칭으로 가리켜서는 안 됩니다. 쓰기는 대상 디렉터리에 단독 생성한 스테이징 파일로 진행해 플러시한 뒤 원자적 이름 바꾸기로 발행합니다

예산, 취소, 직렬화 실패는 기존 대상을 보존하고 발행되지 않은 스테이징 파일을 삭제합니다. 소스는 읽기 전용으로 남습니다

네이티브 주석 검토 PDF는 인증된 어노테이션 권한과 함께 실제 Unicode 하이라이트와 보이는 appearance를 익스포트하고 원본 로드 문서와 서명 리비전을 유지합니다

포맷 경계

현재 프로필은 Standard AES-256 R5·R6 암호화를 지원하고, 지원하지 않는 보안 핸들러와 스트림 필터를 명시적으로 진단하며, 자체 라이터가 표현할 수 없는 퇴역한 free-object 세대는 거절합니다

부트스트랩 xref 스트림은 다이렉트 사전 값과 다이렉트인 bounded Length를 요구합니다. 형식이 틀린 widths, 서브섹션 겹침, Int64를 넘는 부호 없는 오프셋, 압축 멤버 불일치, 참조 순환, 구성된 한도는 타입이 있는 진단을 냅니다

디코딩 콘텐츠는 지원되는 predictor와 간접 스트림 길이를 갖춘 Flate, ASCIIHex, ASCII85, LZW 필터를 지원합니다. 텍스트 추출을 위해 이미지 페이로드를 디코딩하지는 않습니다

네이티브 서명 워크플로는 서명 필드, 보이는 appearance, certification을 다룹니다. 인증된 서명 폼 정책, timestamp, 장기 검증 API는 명시적 무결성·신뢰 옵션을 유지합니다

인수 검증

이름 있는 리치 폰트 패밀리는 SetRichTextFieldValueWithFamilies와 ImportRichFormDataWithFamiliesToFile로 여러 실제 제공 패밀리를 더하며, 기존 필드·보안·트랜잭션 정책을 그대로 씁니다

네이티브 리치 텍스트 필드는 typed 스타일 run, 실제 임베드 스타일 폰트 appearance, 동기화된 V·RV 값, 암호화 증분 출력, bounded 트랜잭션 편집을 제공합니다. GetRichTextFieldValue는 저장되었거나 상속된 XHTML을 읽습니다

Tests/Linux/Run-HeadlessDocumentTests.sh는 데스크톱 변수를 지우고 네이티브 ELF 실행 파일을 빌드해 GUI 라이브러리 의존성을 검사하고, Run-HeadlessDocumentTests-Windows.cmd Win32와 Win64는 같은 공유 문서 API를 실행합니다

반환 값과 타입이 있는 진단은 THPDFHeadlessFormField, EHPDFHeadlessDocumentError, THPDFHeadlessDiagnosticCode를 참고하세요

주석 제거

정확한 페이지와 Unicode NM identity로 페이지 주석을 제거하려면 SaveAnnotationRemovalsToFile를 씁니다. 팝업과 답글 캐스케이드, 유계 준비, 원자적 별개 출력이 함께 적용됩니다

로드된 문서는 변하지 않습니다. 변경 없는 선택은 현재 리비전의 정확한 복사본을 만들고, 증분 제거는 과거 바이트를 유지합니다