HotPDF 안정적인 C 콜백 ABI

HotPDFABI.dll은 고정 폭 상태 값, 불투명 핸들, 명시적 바이트 길이, Lib/hotpdf_abi.h에 선언된 버전 지정 hpdf_io_v1 콜백 구조를 가진 평면 cdecl 함수를 노출합니다

빌드 출력

build-HotPDF-ABI.cmd을 실행하여 Lib/ABI/<platform>/Release 아래에 Win32 및 Win64 DLL과 가져오기 라이브러리를 빌드합니다

공개 ABI는 안정적인 소문자 내보내기 이름을 사용하며, hpdf_abi_version과 hpdf_abi_io_v1_size는 호출자가 문서를 만들기 전에 계약을 검증하게 합니다

핵심 함수

uint32_t hpdf_abi_version(void);
uint32_t hpdf_abi_io_v1_size(void);
hpdf_status hpdf_document_create(hpdf_document *handle);
hpdf_status hpdf_document_destroy(hpdf_document handle);
hpdf_status hpdf_document_load_from_io(
    hpdf_document handle,
    const hpdf_io_v1 *io,
    const char *password,
    size_t password_length);
hpdf_status hpdf_document_page_count(
    hpdf_document handle,
    uint32_t *page_count);
hpdf_status hpdf_document_save_to_io(
    hpdf_document handle,
    const hpdf_io_v1 *io);

버전 지정 I/O 구조

hpdf_io_v1 io = {0};
io.struct_size = sizeof(io);
io.abi_version = HPDF_ABI_VERSION_1;
io.user_data = state;
io.read_at = read_at;
io.get_size = get_size;
io.write = write;
io.is_cancelled = is_cancelled;
io.progress = progress;
io.diagnostic = diagnostic;

struct_size는 Win32에서 48바이트, Win64에서 72바이트이며 flags는 ABI v1에서 0이어야 하고, 더 큰 미래 구조는 필드 레이아웃을 추측하지 않고 구분할 수 있습니다

모든 콜백과 내보낸 함수는 cdecl을 사용하고, 모든 텍스트 포인터는 명시적 바이트 길이를 가지며, Delphi 문자열, 클래스, 인터페이스, 열거형, 예외, Boolean은 경계를 넘지 않습니다

임의 접근 입력

read_at은 절대 64비트 오프셋을 받아 파서의 대상 버퍼에 직접 쓰고, get_size는 소스가 붙을 때 불변 소스 크기를 한 번 보고합니다

부분 성공 읽기는 허용되고 반복 콜백 호출로 완료되므로, range 저장소와 제한된 네트워크 판독기는 중간 완전 파일 버퍼를 할당할 필요가 없습니다

문서 핸들이 파괴되거나 다른 소스가 핸들에 로드될 때까지 콜백 상태와 소스 바이트는 유효하게 남아 있어야 합니다

스트리밍 출력

write는 SaveLoadedDocumentToStream에서 순차 출력 청크를 직접 받습니다. 부분 성공 쓰기는 전체 청크가 수락될 때까지 재시도됩니다

0바이트 성공 쓰기는 앞으로 진행할 수 없으므로 I/O 오류로 거부됩니다

JSON execute와 두 핸들 비교 연산에서는 실패한 write 콜백을 같은 writer와 user-data 쌍으로 다시 호출해 오류 결과를 공개하지 않습니다. OutputIO와 ResultIO가 그 쌍을 공유하는 경우도 포함됩니다. 호출자가 이미 받은 부분 후보 바이트는 호출자 책임으로 남습니다

정의된 0이 아닌 status 범위를 벗어난 write status 값, 그리고 0이거나 과도한 성공 바이트 수는 HPDF_STATUS_IO_ERROR로 취급됩니다. V1 레코드 레이아웃과 부분 성공 쓰기 동작은 바뀌지 않습니다

상태 및 수명 주기

상태	의미
`HPDF_STATUS_OK`	연산이 완료됨
`HPDF_STATUS_INVALID_ARGUMENT`	필수 포인터 또는 콜백이 없거나 바이트 범위가 유효하지 않음
`HPDF_STATUS_INVALID_HANDLE`	핸들이 null, 알 수 없거나 이미 파괴됨
`HPDF_STATUS_INCOMPATIBLE_ABI`	구조 크기, 버전 또는 플래그가 지원되지 않음
`HPDF_STATUS_CANCELLED`	취소 콜백이 종료를 요청함
`HPDF_STATUS_IO_ERROR`	입력 또는 출력 콜백이 실패하거나 개수 계약을 위반함
`HPDF_STATUS_PARSE_ERROR`	입력은 성공적으로 읽혔지만 PDF로 받아들이지 못함
`HPDF_STATUS_INTERNAL_ERROR`	내부 실패가 ABI를 넘기 전에 포착됨

각 성공적인 hpdf_document_create은 성공적인 hpdf_document_destroy 하나와 짝을 이루어야 하며, 반복 파괴는 HPDF_STATUS_INVALID_HANDLE을 반환합니다

불투명 핸들은 객체 주소가 아닌 단조 프로세스 로컬 토큰이므로 할당자 재사용이 오래된 핸들을 부활시킬 수 없습니다

예외는 C 경계를 절대 넘지 않으며, 선택적 진단 콜백은 연산이 오류 상태를 반환하기 전에 해당 메시지 바이트를 받습니다

동시성

서로 다른 핸들은 동시에 사용될 수 있지만, 호출자는 같은 핸들의 연산과 파괴를 직렬화해야 합니다

레거시 Pascal 콜백

THPDFABICallbacks와 HPDFDoc* Pascal 헬퍼는 Delphi 및 C++Builder 응용 프로그램에 대해 소스 호환을 유지하지만, 네이티브 C 통합은 hotpdf_abi.h와 소문자 v1 내보내기를 사용해야 합니다