HotPDF Stable C Callback ABI

HotPDFABI.dll expose des fonctions cdecl plates avec des valeurs de statut de largeur fixe, des poignées opaques, des longueurs d'octets explicites et la structure de rappels versionnée hpdf_io_v1 déclarée dans Lib/hotpdf_abi.h

Sorties de compilation

Exécutez build-HotPDF-ABI.cmd pour compiler les DLL Win32 et Win64 ainsi que les bibliothèques d'importation sous Lib/ABI/<platform>/Release

L'ABI publique utilise des noms d'export stables en minuscules, tandis que hpdf_abi_version et hpdf_abi_io_v1_size permettent aux appelants de vérifier le contrat avant de créer un document

Fonctions principales

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

Structure d'E/S versionnée

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 fait 48 octets sur Win32 et 72 octets sur Win64, flags doit être à zéro pour l'ABI v1, et des structures futures plus grandes peuvent être distinguées sans deviner la disposition des champs

Tous les rappels et fonctions exportés utilisent cdecl, chaque pointeur de texte a une longueur d'octets explicite, et aucune chaîne Delphi, classe, interface, énumération, exception ou Boolean ne franchit la frontière

Entrée à accès aléatoire

read_at reçoit un décalage absolu de 64 bits et écrit directement dans le tampon de destination de l'analyseur, tandis que get_size rapporte la taille source immuable une fois lorsque la source est attachée

Les lectures réussies partielles sont acceptées et complétées par des appels de rappel répétés, de sorte que les magasins de plages et les lecteurs réseau bornés n'ont pas besoin d'allouer un tampon intermédiaire du fichier complet

L'état du rappel et les octets sources doivent rester valides jusqu'à ce que la poignée de document soit détruite ou qu'une autre source soit chargée dans la poignée

Sortie diffusée

write reçoit des morceaux de sortie séquentiels directement depuis SaveLoadedDocumentToStream ; les écritures réussies partielles sont relancées jusqu'à ce que le morceau complet soit accepté

Une écriture réussie de zéro octet est rejetée comme erreur d'E/S car elle ne peut pas progresser

Statut et cycle de vie

Chaque hpdf_document_create réussi doit être apparié avec un hpdf_document_destroy réussi ; une destruction répétée renvoie HPDF_STATUS_INVALID_HANDLE

Les poignées opaques sont des jetons monotones locaux au processus plutôt que des adresses d'objets, de sorte que le recyclage de l'allocateur ne peut pas raviver une poignée obsolète

Les exceptions ne franchissent jamais la frontière C, et le rappel de diagnostic facultatif reçoit les octets de message correspondants avant qu'une opération ne renvoie un statut d'erreur

Concurrence

Des poignées différentes peuvent être utilisées en concurrence, mais les appelants doivent sérialiser les opérations et la destruction pour la même poignée

Rappels Pascal hérités

THPDFABICallbacks et les assistants Pascal HPDFDoc* restent compatibles au niveau source pour les applications Delphi et C++Builder, mais les intégrations C natives doivent utiliser hotpdf_abi.h et les exports v1 en minuscules