JSON and C ABI Document Operations

export.structured는 선택한 page를 semantic HTML, XHTML, XML 또는 JSON으로 내보내고, tables.export는 typed table을 CSV, JSON 또는 XLSX로 내보내며, 페이지 경계를 넘는 연속성, 병합된 셀, 내장 value inference를 그대로 유지합니다

두 연산 모두 binary 출력 destination을 요구하고, 문서와 기존 signature 필드를 보존하며, 상한이 있는 네이티브 내보내기 옵션을 노출합니다

구조화 및 typed table 내보내기

{"schemaVersion":1,"type":"export.structured","pages":[0,1],"format":"html",
 "options":{"imageMode":"metadata","includeFormControls":false}}

{"schemaVersion":1,"type":"tables.export","pages":[0,1],"format":"json",
 "options":{"mergeAcrossPages":true,"dateOrder":"dmy",
            "decimalSeparator":",","thousandsSeparator":"."}}

구조화 내보내기는 html, xhtml, xml, json(기본값)을 받고, table 내보내기는 csv(기본값), json, xlsx를 받습니다

구조화 Boolean 옵션은 includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations, includeFormControls이며 모두 기본값이 true입니다

imageMode는 omit, metadata, embedded-png(기본값)를 받으며, semantic 모델과 민감 필드 동작은 구조화 로드 페이지 내보내기를 참조하세요

구조화 리소스 옵션은 maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes, maxTotalImageBytes입니다

table Boolean 옵션은 detectMergedCells, detectRepeatedHeaders, mergeAcrossPages, inferValueTypes이며 모두 기본값이 true입니다

dateOrder는 ymd(기본값), mdy, dmy를 받고, separator는 인쇄 가능한 문자 하나여야 하며 빈 thousandsSeparator는 이를 비활성화합니다

minimumTableConfidence는 0부터 1까지 받고 기본값은 0.55이며, 양수 columnTolerance의 기본값은 12 page unit입니다

table 리소스 옵션은 maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters, maxOutputBytes이며, cell 모델은 Typed Table Extraction을 참조하세요

알 수 없는 옵션 이름, 잘못된 타입, 지원하지 않는 format, 양수가 아닌 상한은 거부되고, 요청한 네이티브 상한은 보수적인 메모리와 object 예산으로 제한됩니다

내보내기 staging은 budget.outputBytes와 budget.memoryBytes의 1/4 중 작은 값으로 제한되고, effectiveOutputLimit가 그 상한을 보고하며, 더 작은 options.maxOutputBytes가 적용될 수도 있습니다

네이티브 리소스 실패는 budget-exceeded, metric nativeExportResources, 네이티브 진단을 보고하며, observed=1과 limit=0은 측정된 byte 사용량이 아니라 거부된 리소스 조건을 뜻합니다

두 연산 모두 documentUpdated: false를 보고하고, 소스 auto-launch와 decode 설정을 보존하며, 출력을 공개 전에 staging하고, 파일 job이 실패해도 기존 파일 destination을 유지합니다

마감 시간과 ABI callback 취소 검사는 연산과 공개 checkpoint에서 협조적으로 수행되고, 네이티브 cancellation token은 지원되는 extraction 단계 안에서도 적용되지만 네이티브 작업이 강제로 중단되지는 않습니다

THPDFJobProcessor.ExecuteLoadedOperation과 hpdf_document_execute_json_v1은 같은 schema-version 문서 연산 엔진을 공유합니다

현재 연산 이름, format, signing profile, callback 동작, 기본 예산은 THPDFJobProcessor.Capabilities 또는 hpdf_capabilities_json_to_io로 확인하세요

연산

연산 JSON은 UTF-8과 schemaVersion: 1을 사용하고, page index는 0부터 시작하며 선택한 page 배열에는 중복이 있으면 안 됩니다

네이티브 치환 API가 match를 인코딩하지 못하면 text 치환은 partial status를 반환하므로 페이지별 개수를 확인하세요

OCR은 현재 내장 ASCII 엔진만 노출하고, 네이티브 Delphi API는 외부 OCR adapter를 받습니다

변경 연산은 서명되지 않은 placeholder를 포함해 기존 signature 필드가 있는 문서를 거부하므로, 그런 문서에서 서명을 보존하려면 네이티브 incremental API를 사용하세요

증분 PFX 서명은 변경되지 않은 보유 원본을 받아들이며, 명시적 작업 패스워드를 쓰는 지원되는 암호화 PDF를 포함해 기존/신규 CMS를 모두 검증하고, 원본 바이트와 암호화를 보존하고, 기존 빈 필드를 지원하고, 암호화 권한을 확인하고, 소스/출력 파일 별칭은 거부합니다

서명은 signed artifact를 남기고 원래 handle을 복원하면서 documentUpdated: false를 보고하고, 기존 form 필드는 계속 쓸 수 있고, 임시 signature 필드는 제거되며, 서명 뒤에는 handle을 조회하거나 다른 연산에 쓸 수 있습니다

PDF/A-4 raster 아카이브 변환

{
  "schemaVersion": 1,
  "type": "archive.pdfa4.raster",
  "acceptInformationLoss": true,
  "iccProfileFile": "profiles/sRGB.icm",
  "dpi": 150,
  "input": "source.pdf",
  "output": "archive.pdf"
}

이 object를 file job의 operations 배열에 넣거나, 로드된 handle과 binary 출력 callback으로 hpdf_document_execute_json_v1에 직접 넘길 수 있으며, C ABI는 file-job 입력/출력 경로를 무시하고 자기 adapter를 사용합니다

acceptInformationLoss는 JSON Boolean true여야 하고, iccProfileFile은 실행 호스트에 있는 지원되는 sRGB matrix/TRC ICC profile을 가리키는 비어 있지 않고 NUL이 없는 경로여야 하며, 상대 profile 경로는 프로세스 작업 디렉터리 기준으로 해석됩니다

dpi는 기본값이 150이고 36부터 1,200까지의 정수를 받으며, 변환은 모든 소스 page를 대상으로 하고 pages 멤버가 있으면 거부합니다

archive 결과 object는 nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields, removedEmbeddedFiles를 보고합니다

archive.lossy는 true이고 archive.lossProfile의 모든 flag, 즉 searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances, structureIdentity는 false입니다

page 내용은 RGB pixel이 되고 annotation과 widget appearance는 빠지며 원본 서명은 출력으로 옮겨지지 않고, 로드된 소스는 공개가 실패한 뒤에도 documentUpdated: false로 계속 쓸 수 있으며 이전 launch, decode, stream-threshold, 취소, render 설정이 복원됩니다

binary 출력이 필수이고 전달 전에 네이티브 PDF/A-4 검증이 성공해야 하며, rendering, color, codec, 소스 alias, conformance 경계는 로드된 PDF/A-4 raster 변환을 참조하세요

아카이브 리소스 예산

선택적 options object는 아래 effective cap을 더 줄이는 양의 정확한 정수를 받으며, 알 수 없는 key와 cap을 넘는 값은 연산 예산을 늘리는 대신 요청을 거부합니다

ICC 파일은 할당 전에 4 MiB와 memoryBytes / 16 중 작은 값으로 제한되며, 이 보수적인 여유는 동시에 진행되는 staging, 출력 buffer, image data, decoder 작업을 감안한 것으로 엄격한 프로세스 RSS 상한은 아닙니다

더 큰 아카이브 작업량이 의도된 거라면 최상위 job 예산을 늘리면 되고, 중첩 options는 effective cap을 줄일 뿐이며 네이티브 최대값은 그대로 적용됩니다

아카이브 checkpoint는 변환 중 callback 취소, 빌린 소스 cancellation token, 경과 시간, object 개수를 poll합니다. 예산과 취소 실패는 네이티브 converter 전체에서 구조화된 status code를 유지합니다

File job

{
  "operations": [
    {"type": "capabilities"},
    {"schemaVersion": 1, "type": "text.extract", "input": "input.pdf",
     "pages": [0, 1], "output": "text.txt"}
  ]
}

THPDFJobProcessor.Execute는 operations 배열을 받고 최대 1,024개 연산과 4 MiB JSON까지 허용하며, 기존 merge, split, optimise, encrypt, validate job도 계속 쓸 수 있습니다

각 문서 연산은 입력 경로와 선택적 password를 공급하며, render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign, archive.pdfa4.raster는 출력 경로가 필요합니다

artifact는 destination 옆 임시 파일에 기록되고 flush와 검증을 거친 뒤 atomic하게 공개되며, 실패 시 기존 destination을 보존하고 입력/출력이 같은 경로를 공유할 수 있습니다

C callback 계약

hpdf_operation_v1을 0으로 초기화하고 struct_size는 네이티브 크기로, abi_version은 HPDF_ABI_VERSION_1로, flag는 0으로 설정한 뒤 크기를 hpdf_abi_operation_v1_size와 비교하세요

연산 record는 JSON byte와 정확한 길이, 선택적 random-access 입력, 선택적 sequential binary 출력, 필수 sequential JSON 결과 출력을 담습니다

lazy 파싱이 adapter를 붙잡고 있으므로 입력 callback, user data, 뒤를 받치는 PDF byte는 handle이 교체되거나 파괴될 때까지 유효해야 합니다

출력/결과 callback은 호출 중에만 존재하니 handle별로 호출을 직렬화하고 callback 재진입은 피하세요

callback은 cdecl을 쓰고 부분 전송은 재시도되며, 성공한 쓰기는 양의 진행을 만들어야 하고, exception은 고정 status code로 변환됩니다

변경은 artifact와 JSON 결과 전달이 모두 성공한 뒤에만 commit되고, callback 실패나 취소는 변경을 rollback하며, caller는 이미 전달된 byte를 버립니다

치환 입력은 변경 transaction 전에 로드되며 별도의 state 변경으로 남습니다

예산

선택적 budget object는 9,007,199,254,740,991을 넘지 않는 양의 정확한 정수를 받습니다

일반 output/result 예산은 각각 메모리 예산의 절반으로 제한되고, 아카이브 변환은 위의 더 엄격한 cap을 적용합니다. 이 값들은 전체 프로세스 메모리가 아니라 설정된 연산 리소스를 묶는 것입니다

취소와 경과 시간 검사는 연산, page, 입력 읽기, 출력 쓰기 checkpoint에서 협조적으로 수행되며, 길게 도는 네이티브 routine은 다음 checkpoint까지 계속될 수 있습니다

report는 schemaVersion, status, statusCode를 담고, budget 오류는 status 8, 취소 4, I/O 실패 5, parse 실패 6, 잘못된 인자 1, 실행 실패 7을 씁니다