Stabiele C-callback-ABI van HotPDF

HotPDFABI.dll stelt platte cdecl-functies beschikbaar met statuswaarden van vaste breedte, ondoorzichtige handles, expliciete bytelengten en de geversioneerde hpdf_io_v1-callbackstructuur die in Lib/hotpdf_abi.h is gedeclareerd

Build-uitvoer

Voer build-HotPDF-ABI.cmd uit om Win32- en Win64-DLL's plus importbibliotheken te bouwen onder Lib/ABI/<platform>/Release

De openbare ABI gebruikt stabiele exportnamen in kleine letters, terwijl hpdf_abi_version en hpdf_abi_io_v1_size aanroepers in staat stellen het contract te verifiëren vóór het maken van een document

Kernfuncties

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

Gevoerde I/O-structuur

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 is 48 bytes op Win32 en 72 bytes op Win64, flags moet nul zijn voor ABI v1, en grotere toekomstige structuren kunnen worden onderscheiden zonder de veldlay-out te raden

Alle callbacks en geëxporteerde functies gebruiken cdecl, elke tekstpointer heeft een expliciete bytelengte, en geen Delphi-string, klasse, interface, enum of Boolean overschrijdt de grens

Willekeurige-toegang invoer

read_at ontvangt een absolute 64-bits offset en schrijft rechtstreeks naar de doellocatie van de parser, terwijl get_size de onveranderlijke bronomvang eenmaal meldt wanneer de bron is gekoppeld

Gedeeltelijk geslaagde leesbewerkingen worden geaccepteerd en via herhaalde callback-aanroepen voltooid, zodat reeksopslagen en begrensde netwerklezers geen tussentijdse volledige-bestandsbuffer hoeven toe te wijzen

De callbackstatus en bronbytes moeten geldig blijven totdat de documenthandle is vernietigd of een andere bron in de handle is geladen

Gestreamde uitvoer

write ontvangt opeenvolgende uitvoerblokken rechtstreeks van SaveLoadedDocumentToStream; gedeeltelijk geslaagde schrijfbewerkingen worden opnieuw geprobeerd totdat het volledige blok is geaccepteerd

Een geslaagd schrijven van nul bytes wordt als I/O-fout afgewezen omdat het geen vooruitgang kan boeken

Voor JSON-execute- en twee-handle-vergelijkingsoperaties wordt een mislukte write-callback niet opnieuw aangeroepen om een errorresultaat via hetzelfde writer-/user-data-paar te publiceren, ook niet wanneer OutputIO en ResultIO dat paar delen; partiële kandidaatbytes die de aanroeper al heeft ontvangen blijven de verantwoordelijkheid van de aanroeper

Write-statuswaarden buiten de gedefinieerde niet-nul statusrange en nul of buitensporige aantallen geslaagde bytes worden HPDF_STATUS_IO_ERROR; de V1-recordlayout en het geslaagde partiële-schrijfgedrag blijven ongewijzigd

Status en levenscyclus

Status	Betekenis
`HPDF_STATUS_OK`	De bewerking is voltooid
`HPDF_STATUS_INVALID_ARGUMENT`	Een vereiste pointer of callback ontbreekt of een bytereeks is ongeldig
`HPDF_STATUS_INVALID_HANDLE`	De handle is null, onbekend of al vernietigd
`HPDF_STATUS_INCOMPATIBLE_ABI`	De structuurgrootte, versie of flags worden niet ondersteund
`HPDF_STATUS_CANCELLED`	De annuleringscallback verzocht om beëindiging
`HPDF_STATUS_IO_ERROR`	Een invoer- of uitvoercallback mislukte of schond zijn tellingscontract
`HPDF_STATUS_PARSE_ERROR`	De invoer werd succesvol gelezen maar werd niet als PDF geaccepteerd
`HPDF_STATUS_INTERNAL_ERROR`	Een interne fout werd opgevangen voordat deze de ABI overschreed

Elke geslaagde hpdf_document_create moet worden gekoppeld aan één geslaagde hpdf_document_destroy; herhaalde vernietiging retourneert HPDF_STATUS_INVALID_HANDLE

Ondoorzichtige handles zijn monotone proceslokale tokens in plaats van objectadressen, zodat hergebruik door de toewijzer een verlopen handle niet kan doen herleven

Uitzonderingen overschrijden de C-grens nooit, en de optionele diagnostische callback ontvangt de overeenkomstige berichtbytes vóór een bewerking een foutstatus retourneert

Gelijktijdigheid

Verschillende handles kunnen gelijktijdig worden gebruikt, maar aanroepers moeten bewerkingen en vernietiging voor dezelfde handle serialiseren

Verouderde Pascal-callbacks

THPDFABICallbacks en de Pascal-helpers HPDFDoc* blijven broncompatibel voor Delphi- en C++Builder-applicaties, maar native C-integraties moeten hotpdf_abi.h en de exports in kleine letters van v1 gebruiken