HotPDF stabil C-callback-ABI

HotPDFABI.dll eksponerer flade cdecl-funktioner med statusværdier med fast bredde, opaque handles, eksplicitte bytellængder og den versionerede callback-struktur hpdf_io_v1, som er deklareret i Lib/hotpdf_abi.h

Build-output

Kør build-HotPDF-ABI.cmd for at bygge Win32- og Win64-DLL'er samt importbiblioteker under Lib/ABI/<platform>/Release

Den offentlige ABI bruger stabile eksportnavne med små bogstaver, mens hpdf_abi_version og hpdf_abi_io_v1_size lader kaldere bekræfte kontrakten, før et dokument oprettes

Kernefunktioner

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

Versioneret I/O-struktur

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 er 48 bytes på Win32 og 72 bytes på Win64, flags skal være nul for ABI v1, og større fremtidige strukturer kan skelnes uden at gætte feltlayout

Alle callbacks og eksporterede funktioner bruger cdecl, hver tekstpointer har en eksplicit bytellængde, og ingen Delphi-streng, klasse, grænseflade, enum, undtagelse eller Boolean krydser grænsen

Input med random access

read_at modtager en absolut 64-bit-forskydning og skriver direkte til parserens destinationsbuffer, mens get_size rapporterer den uforanderlige kildestørrelse én gang, når kilden tilknyttes

Delvise vellykkede læsninger accepteres og fuldføres gennem gentagne callback-kald, så range stores og afgrænsede netværkslæsere ikke behøver at allokere en mellemliggende komplet filbuffer

Callback-tilstanden og kildebytes skal forblive gyldige, indtil dokumenthandlet ødelægges, eller en anden kilde indlæses i handlet

Streamet output

write modtager sekventielle outputstykker direkte fra SaveLoadedDocumentToStream, og delvise vellykkede skrivninger prøves igen, indtil hele stykket er accepteret

En vellykket skrivning på nul bytes afvises som en I/O-fejl, fordi den ikke kan gøre fremdrift

Ved JSON execute- og two-handle comparison-operationer kaldes en fejlet write-callback ikke igen for at publicere et fejlsvar gennem samme writer- og user-data-par, inklusive når OutputIO og ResultIO deler det par; delvise kandidat-bytes, kalderen allerede har modtaget, forbliver kalderens ansvar

Write-statusværdier uden for det definerede nonzero-statusinterval samt nul eller overdrevne vellykkede byte-antal bliver til HPDF_STATUS_IO_ERROR; V1-record-layoutet og delvise vellykkede skrivninger forbliver uændrede

Status og livscyklus

Status	Betydning
`HPDF_STATUS_OK`	Handlingen blev fuldført
`HPDF_STATUS_INVALID_ARGUMENT`	En påkrævet pointer eller callback mangler, eller et byteområde er ugyldigt
`HPDF_STATUS_INVALID_HANDLE`	Handlet er null, ukendt eller allerede ødelagt
`HPDF_STATUS_INCOMPATIBLE_ABI`	Strukturens størrelse, version eller flag understøttes ikke
`HPDF_STATUS_CANCELLED`	Annullerings-callbacken anmodede om afslutning
`HPDF_STATUS_IO_ERROR`	En input- eller output-callback mislykkedes eller overtrådte sin tællekontrakt
`HPDF_STATUS_PARSE_ERROR`	Input blev læst, men blev ikke accepteret som en PDF
`HPDF_STATUS_INTERNAL_ERROR`	En intern fejl blev fanget, før den krydsede ABI'en

Hver vellykket hpdf_document_create skal parres med én vellykket hpdf_document_destroy, og gentagen ødelæggelse returnerer HPDF_STATUS_INVALID_HANDLE

Opaque handles er monotone proceslokale tokens frem for objektadresser, så genbrug af allokatorer ikke kan genoplive et forældet handle

Undtagelser krydser aldrig C-grænsen, og den valgfri diagnostiske callback modtager de tilsvarende beskedbytes, før en handling returnerer en fejlstatus

Samtidighed

Forskellige handles må bruges samtidigt, men kaldere skal serialisere handlinger og ødelæggelse for samme handle

Ældre Pascal-callbacks

THPDFABICallbacks og Pascal-hjælperne HPDFDoc* forbliver kildekompatible med Delphi- og C++Builder-applikationer, men oprindelige C-integrationer bør bruge hotpdf_abi.h og v1-eksporterne med små bogstaver