ABI zpětného volání HPDFDoc

HotPDFABI.dll zpřístupňuje ploché funkce cdecl se stavovými hodnotami pevné šířky, neprůhlednými handly, explicitními délkami bajtů a verzovanou strukturou zpětných volání hpdf_io_v1 deklarovanou v Lib/hotpdf_abi.h

Výstupy sestavení

Spusťte build-HotPDF-ABI.cmd a sestavíte DLL Win32 a Win64 včetně importních knihoven pod Lib/ABI/<platform>/Release

Veřejné ABI používá stabilní exportní názvy malými písmeny, zatímco hpdf_abi_version a hpdf_abi_io_v1_size umožňují volajícím ověřit smlouvu dřív, než vytvoří dokument

Základní funkce

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

Verzovaná I/O struktura

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 je 48 bajtů na Win32 a 72 bajtů na Win64, flags musí být u ABI v1 nula a větší budoucí struktury lze rozlišit bez hádání rozvržení polí

Všechna zpětná volání i exportované funkce používají cdecl, každý textový ukazatel má explicitní délku v bajtech a přes hranici neprochází žádný delphiovský řetězec, třída, rozhraní, enum, výjimka ani Boolean

Vstup s náhodným přístupem

read_at obdrží absolutní 64bitový posun a zapisuje přímo do cílového bufferu parseru, zatímco get_size hlásí neměnnou velikost zdroje jednou, jakmile se zdroj připojí

Částečně úspěšná čtení se přijímají a dokončují opakovanými voláními zpětného volání, takže range úložiště i omezení síťová čtenáři nemusí alokovat mezibuffer celého souboru

Stav zpětného volání i zdrojové bajty musí zůstat platné, dokud se handle dokumentu nezničí nebo dokud se do něj nenačte jiný zdroj

Streamovaný výstup

write dostává sekvenční výstupní bloky přímo z SaveLoadedDocumentToStream; částečně úspěšné zápisy se opakují, dokud se nepřijme celý blok

Úspěšný zápis nula bajtů se odmítne jako I/O chyba, protože nemůže zajistit pokrok

U operací JSON execute a porovnání dvou handle se neúspěšný write callback znovu nevolá, aby přes tutéž dvojici writer a user-data publikoval chybový výsledek, včetně případu, kdy OutputIO a ResultIO sdílejí tuhle dvojici; částečné candidate bytes už předané volajícímu zůstávají jeho odpovědností

Stavové hodnoty zápisu mimo definovaný nenulový rozsah stavů a nulové či přehnané počty úspěšných bajtů se stanou HPDF_STATUS_IO_ERROR; rozložení záznamu V1 i chování částečného úspěšného zápisu zůstávají beze změny

Stavy a životní cyklus

Stav	Význam
`HPDF_STATUS_OK`	Operace se dokončila
`HPDF_STATUS_INVALID_ARGUMENT`	Chybí požadovaný ukazatel nebo zpětné volání, případně je bajtový rozsah neplatný
`HPDF_STATUS_INVALID_HANDLE`	Handle je null, neznámý nebo už zničený
`HPDF_STATUS_INCOMPATIBLE_ABI`	Velikost struktury, verze nebo příznaky nejsou podporovány
`HPDF_STATUS_CANCELLED`	Zpětné volání zrušení požádalo o ukončení
`HPDF_STATUS_IO_ERROR`	Vstupní nebo výstupní zpětné volání selhalo nebo porušilo smlouvu o počtech
`HPDF_STATUS_PARSE_ERROR`	Vstup se úspěšně přečetl, ale nebyl přijat jako PDF
`HPDF_STATUS_INTERNAL_ERROR`	Vnitřní selhání se zachytilo dřív, než překročilo ABI

Každé úspěšné hpdf_document_create se musí spárovat s jedním úspěšným hpdf_document_destroy; opakované ničení vrátí HPDF_STATUS_INVALID_HANDLE

Neprůhledné handly jsou monotónní tokeny lokální pro proces, nikoli adresy objektů, takže znovupoužití alokátoru nemůže oživit zastaralý handle

ABI zpětného volání HPDFDoc definuje stabilní smlouvu mezi HotPDF a hostitelskými obslužnými programy nebo integračními komponentami

Smlouva

Struktury a funkce mají pevně určené verze, velikosti a pravidla vlastnictví. Implementace musí ověřit velikost vstupní struktury a respektovat omezení zdrojů volání

Starší pascalovská zpětná volání

Chyby se vracejí jako definované stavy a diagnostika, nikoli jako výjimky přes hranici ABI Typy THPDFABICallbacks a pascalovské helpery HPDFDoc* zůstávají zdrojově kompatibilní pro aplikace Delphi a C++Builder, nativní integrace v C by ale měly používat hotpdf_abi.h