HotPDF Kararlı C Callback ABI'si

HotPDFABI.dll; sabit genişlikte status değerleri, opaque handle'lar, açık bayt uzunlukları ve Lib/hotpdf_abi.h içinde tanımlanan sürümlü hpdf_io_v1 callback yapısıyla düz cdecl fonksiyonlar sunar

Build çıktıları

Lib/ABI/<platform>/Release altında Win32 ve Win64 DLL'lerini ve import library'lerini build etmek için build-HotPDF-ABI.cmd dosyasını çalıştırın

Public ABI kararlı, küçük harfli export adları kullanır; hpdf_abi_version ve hpdf_abi_io_v1_size ise çağıranların sözleşmeyi belge oluşturmadan önce doğrulamasını sağlar

Çekirdek fonksiyonlar

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

Sürümlü I/O yapısı

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 Win32'de 48 bayt, Win64'te 72 bayttır; flags ABI v1 için sıfır olmalıdır ve gelecekteki daha büyük yapılar, field düzeni tahmin edilmeden ayırt edilebilir

Tüm callback'ler ve export edilen fonksiyonlar cdecl kullanır, her text pointer açık bir bayt uzunluğuna sahiptir ve sınırı hiçbir Delphi string, class, interface, enum, exception ya da Boolean geçmez

Random-access girdi

read_at mutlak bir 64-bit offset alır ve doğrudan parser'ın hedef tamponuna yazar; get_size ise kaynak eklendiğinde değişmez kaynak boyutunu bir kez bildirir

Kısmi başarılı okumalar kabul edilir ve tekrarlanan callback çağrılarıyla tamamlanır; böylece range store'lar ve sınırlı network reader'ları ara bir tam dosya tamponu ayırmak zorunda kalmaz

Callback durumu ve kaynak baytları, document handle yok edilene ya da handle'a başka bir kaynak yüklenene kadar geçerli kalmalıdır

Stream'lenen çıktı

write, sıralı output chunk'larını doğrudan SaveLoadedDocumentToStream'den alır; kısmi başarılı yazmalar, chunk'ın tamamı kabul edilene dek yeniden denenir

Sıfır baytlık başarılı bir yazma, ilerleme kaydedemediği için I/O hatası olarak reddedilir

JSON execute ve iki-handle'lı karşılaştırma operation'ları için, başarısız bir write callback'i — OutputIO ve ResultIO o çifti paylaştığında bile — hata sonucunu aynı writer ve user-data çifti üzerinden yayımlamak için yeniden çağrılmaz; çağıranın zaten aldığı kısmi aday baytları çağıranın sorumluluğundadır

Tanımlanmış sıfırdan-farklı status aralığının dışındaki yazma status value'ları ve sıfır veya aşırı başarılı bayt sayıları HPDF_STATUS_IO_ERROR olur; V1 record layout'u ve başarılı kısmi-yazma davranışı değişmeden kalır

Status ve yaşam döngüsü

Status	Anlam
`HPDF_STATUS_OK`	İşlem tamamlandı
`HPDF_STATUS_INVALID_ARGUMENT`	Zorunlu bir pointer ya da callback yok ya da bir byte range geçersiz
`HPDF_STATUS_INVALID_HANDLE`	Handle null, bilinmiyor ya da çoktan yok edilmiş
`HPDF_STATUS_INCOMPATIBLE_ABI`	Yapı boyutu, sürüm ya da flags desteklenmiyor
`HPDF_STATUS_CANCELLED`	Cancellation callback'i sonlandırmayı istedi
`HPDF_STATUS_IO_ERROR`	Bir input ya da output callback'i başarısız oldu ya da count sözleşmesini ihlal etti
`HPDF_STATUS_PARSE_ERROR`	Input başarıyla okundu ama PDF olarak kabul edilmedi
`HPDF_STATUS_INTERNAL_ERROR`	Dahili bir hata, ABI'yi geçmeden önce yakalandı

Her başarılı hpdf_document_create, başarılı bir hpdf_document_destroy ile eşleşmelidir; tekrarlanan yok etme HPDF_STATUS_INVALID_HANDLE döndürür

Opaque handle'lar, nesne adresleri yerine monotonik process-local token'lardır; böylece allocator yeniden kullanımı bayat bir handle'ı canlandıramaz

Exception'lar asla C sınırını geçmez ve opsiyonel diagnostic callback, bir işlem hata status'u döndürmeden önce ilgili mesaj baytlarını alır

Eşzamanlılık

Farklı handle'lar eşzamanlı kullanılabilir; ancak aynı handle için işlemlerin ve yok etmenin serialize edilmesi çağıranın sorumluluğundadır

Eski Pascal callback'leri

THPDFABICallbacks ve HPDFDoc* Pascal helper'ları, Delphi ve C++Builder uygulamaları için kaynak uyumlu kalır; ancak native C entegrasyonları hotpdf_abi.h ve küçük harfli v1 export'larını kullanmalıdır