HotPDF stabil C-callback-ABI

HotPDFABI.dll exponerar platta cdecl-funktioner med fastbreddsstatusvärden, ogenomskinliga handtag, explicita bytlängder och den versionsstämplade hpdf_io_v1-callbackstrukturen som deklareras i Lib/hotpdf_abi.h

Byggutdata

Kör build-HotPDF-ABI.cmd för att bygga Win32- och Win64-DLL:er samt importbibliotek under Lib/ABI/<platform>/Release

Den publika ABI:n använder stabila lowercase-exportnamn, medan hpdf_abi_version och hpdf_abi_io_v1_size låter anropare verifiera kontraktet innan de skapar ett dokument

Kärnfunktioner

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

Versionsstämplad 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 är 48 byte på Win32 och 72 byte på Win64, flags måste vara noll för ABI v1, och större framtida strukturer kan särskiljas utan att gissa fältlayout

Alla callbacks och exporterade funktioner använder cdecl, varje textpekare har en explicit bytlängd och ingen Delphi-sträng, klass, gränssnitt, enum, undantag eller Boolean korsar gränsen

Slumpmässig access-indata

read_at tar emot en absolut 64-bitsoffset och skriver direkt till parserens destinationsbuffert, medan get_size rapporterar den oföränderliga källstorleken en gång när källan är ansluten

Partiella lyckade läsningar accepteras och slutförs genom upprepade callback-anrop, så att intervalllagringar och begränsade nätverksläsare inte behöver allokera en mellanliggande komplett-filbuffert

Callbacktillståndet och källbyten måste förbli giltiga tills dokumenthandtaget förstörts eller en annan källa laddas i handtaget

Strömmad utdata

write tar emot sekventiella utdatalenbitar direkt från SaveLoadedDocumentToStream; partiella lyckade skriv försöks igen tills hela lenbiten accepteras

Ett lyckat nollbyte-skriv avvisas som ett I/O-fel eftersom det inte kan göra framsteg framåt

För JSON-körning och två-handle-jämförelseoperationer anropas ett misslyckat skrivåteranrop inte igen för att publicera ett felresultat genom samma writer- och user-data-par, inklusive när OutputIO och ResultIO delar det paret; partiella kandidatbyte som anroparen redan tagit emot förblir anroparens ansvar

Skrivstatusvärden utanför det definierade icke-noll-statusintervallet, samt noll eller överdrivna lyckade byteantal, blir HPDF_STATUS_IO_ERROR; V1-postlayouten och lyckat partiellt skrivbeteende förblir oförändrade

Status och livscykel

Varje lyckad hpdf_document_create måste paras ihop med en lyckad hpdf_document_destroy; upprepad destruktion returnerar HPDF_STATUS_INVALID_HANDLE

Ogenomskinliga handtag är monotona processlokala token snarare än objektadresser, så allokeringsåteranvändning kan inte återuppliva ett inaktuellt handtag

Undantag korsar aldrig C-gränsen och den valfria diagnostik-callbacken tar emot motsvarande meddelandebyte innan en operation returnerar en felstatus

Konkurrens

Olika handtag kan användas samtidigt, men anropare måste serialisera operationer och destruktion för samma handtag

Äldre Pascal-callbacks

THPDFABICallbacks och HPDFDoc*-Pascalhjälparna förblir källkompatibla för Delphi- och C++Builder-applikationer, men inbyggda C-integreringar bör använda hotpdf_abi.h och lowercase v1-exportnamnen