HotPDF ABI Callback C Stabile

HotPDFABI.dll espone funzioni cdecl piatte con valori di stato a larghezza fissa, handle opachi, lunghezze esplicite in byte e la struttura callback versionata hpdf_io_v1 dichiarata in Lib/hotpdf_abi.h

Output della build

Esegui build-HotPDF-ABI.cmd per compilare DLL Win32 e Win64 oltre alle librerie di import sotto Lib/ABI/<platform>/Release

L'ABI pubblica usa nomi di export minuscoli e stabili, mentre hpdf_abi_version e hpdf_abi_io_v1_size consentono ai chiamanti di verificare il contratto prima di creare un documento

Funzioni principali

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

Struttura I/O versionata

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 è di 48 byte su Win32 e di 72 byte su Win64, flags deve essere zero per l'ABI v1 e le strutture future più grandi possono essere riconosciute senza indovinare la disposizione dei campi

Tutte le callback e le funzioni esportate usano cdecl, ogni puntatore di testo ha una lunghezza esplicita in byte e nessuna stringa Delphi, classe, interfaccia, enum, eccezione o Boolean attraversa il confine

Input ad accesso casuale

read_at riceve un offset assoluto a 64 bit e scrive direttamente nel buffer di destinazione del parser, mentre get_size riporta la dimensione immutabile della sorgente una volta quando la sorgente viene collegata

Le letture parziali riuscite sono accettate e completate tramite chiamate ripetute della callback, così gli archivi di range e i reader di rete con limiti non devono allocare un buffer intermedio per il file completo

Lo stato della callback e i byte della sorgente devono restare validi fino alla distruzione dell'handle del documento o fino al caricamento di un'altra sorgente nell'handle

Output in streaming

write riceve i blocchi di output sequenziali direttamente da SaveLoadedDocumentToStream; le scritture parziali riuscite vengono riprovate finché il blocco completo non viene accettato

Una scrittura riuscita di zero byte viene rifiutata come errore I/O perché non può progredire

Per le operazioni di execute JSON e confronto a due handle, una callback di scrittura fallita non viene richiamata per pubblicare un risultato di errore attraverso la stessa coppia writer e user-data, incluso quando OutputIO e ResultIO condividono quella coppia; i byte parziali del candidato già ricevuti dal chiamante restano responsabilità del chiamante

Valori di stato fuori dall'intervallo di stati non zero definito, e conteggi riusciti di byte nulli o eccessivi, diventano HPDF_STATUS_IO_ERROR; il layout del record V1 e il comportamento di scrittura parziale riuscita restano invariati

Stato e ciclo di vita

Stato	Significato
`HPDF_STATUS_OK`	L'operazione è stata completata
`HPDF_STATUS_INVALID_ARGUMENT`	Un puntatore o una callback richiesta è assente o un intervallo di byte non è valido
`HPDF_STATUS_INVALID_HANDLE`	L'handle è nullo, sconosciuto o già distrutto
`HPDF_STATUS_INCOMPATIBLE_ABI`	La dimensione, la versione o i flags della struttura non sono supportati
`HPDF_STATUS_CANCELLED`	La callback di cancellazione ha richiesto la terminazione
`HPDF_STATUS_IO_ERROR`	Una callback di input o output è fallita o ha violato il proprio contratto di conteggio
`HPDF_STATUS_PARSE_ERROR`	L'input è stato letto con successo ma non è stato accettato come PDF
`HPDF_STATUS_INTERNAL_ERROR`	Un guasto interno è stato intercettato prima che attraversasse l'ABI

Ogni hpdf_document_create riuscito deve essere accoppiato con un hpdf_document_destroy riuscito; una distruzione ripetuta restituisce HPDF_STATUS_INVALID_HANDLE

Gli handle opachi sono token process-local monotoni anziché indirizzi di oggetto, così il riuso dell'allocator non può far rivivere un handle obsoleto

Le eccezioni non attraversano mai il confine C e la callback diagnostica opzionale riceve i byte del messaggio corrispondente prima che un'operazione restituisca uno stato di errore

Concorrenza

Handle diversi possono essere usati contemporaneamente, ma i chiamanti devono serializzare le operazioni e la distruzione per lo stesso handle

Callback Pascal legacy

THPDFABICallbacks e gli helper Pascal HPDFDoc* restano compatibili a livello di sorgente per le applicazioni Delphi e C++Builder, ma le integrazioni C native dovrebbero usare hotpdf_abi.h e gli export minuscoli v1