ABI callback C المستقر لـ HotPDF

HotPDFABI.dll exposes flat cdecl functions with fixed-width status values, opaque handles, explicit byte lengths, and the versioned hpdf_io_v1 callback structure declared in Lib/hotpdf_abi.h

مخرجات البناء

Run build-HotPDF-ABI.cmd to build Win32 and Win64 DLLs plus import libraries under Lib/ABI/<platform>/Release

The public ABI uses stable lowercase export names, while hpdf_abi_version and hpdf_abi_io_v1_size let callers verify the contract before creating a document

الدوال الأساسية

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

بنية الإدخال/الإخراج المسنودة بالإصدارات

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 on Win32 and 72 bytes on Win64, flags must be zero for ABI v1, and larger future structures can be distinguished without guessing field layout

All callbacks and exported functions use cdecl, every text pointer has an explicit byte length, and no Delphi string, class, interface, enum, exception, or Boolean crosses the boundary

إدخال وصول عشوائي

read_at receives an absolute 64-bit offset and writes directly into the parser's destination buffer, while get_size reports the immutable source size once when the source is attached

القراءات الناجحة الجزئية مقبولة وتكتمل عبر استدعاءات callback متكررة، فمخازن المدايات وقارئو الشبكة المحدودون بحدود لا يحتاجون حجز مخزن ملف-كامل وسيطًا

حالة callback وبايتات المصدر يجب أن تبقى صالحة حتى يُتلف مقبض المستند أو يُحمل مصدر آخر إلى المقبض

إخراج متدفق

write receives sequential output chunks directly from SaveLoadedDocumentToStream; partial successful writes are retried until the complete chunk is accepted

كتابة ناجحة صفرية البايتات تُرفض كخطأ إدخال/إخراج لأنها لا تحقق تقدمًا

لعمليات تنفيذ JSON والمقارنة بمقبضتين، callback الكتابة الفاشلة لا تستدعى مجددًا لنشر نتيجة خطأ عبر ثنائية الكاتب وبيانات المستخدم نفسها، بما يشمل عندما تتقاسم OutputIO وResultIO تلك الثنائية؛ وبايتات المرشح الجزئية التي تلقاها المستدعي سلفًا تبقى مسؤوليته

قيم حالة الكتابة خارج مدى الحالة غير الصفرية المعرّف وعدادات بايتات ناجحة صفرية أو زائدة تصير HPDF_STATUS_IO_ERROR؛ وتخطيط سجل V1 وسلوك الكتابة الجزئية الناجحة يبقيان غير متغيرين

الحالة ودورة الحياة

Each successful hpdf_document_create must be paired with one successful hpdf_document_destroy; repeated destruction returns HPDF_STATUS_INVALID_HANDLE

المقبضات الشفافة مدخلات رتيبة خاصة بالعملية لا عناوين كائنات، فلا يستطيع إعادة استخدام الحاجز إحياء مقبض متقادم

الاستثناءات لا تعبر حد C أبدًا، وتتلقى callback التشخيص الاختيارية بايتات الرسالة المقابلة قبل أن تُعيد العملية حالة خطأ

التزامن

المقبضات المختلفة يمكن استخدامها متزامنةً، لكن على المستدعين تسلسل العمليات والإتلاف للمقبض نفسه

callbacks Pascal القديمة

THPDFABICallbacks and the HPDFDoc* Pascal helpers remain source compatible for Delphi and C++Builder applications, but native C integrations should use hotpdf_abi.h and the lowercase v1 exports