HotPDF 安定 C コールバック ABI

HotPDFABI.dll は、固定幅のステータス値、不透明ハンドル、明示的なバイト長、および Lib/hotpdf_abi.h で宣言されたバージョン管理された hpdf_io_v1 コールバック構造を持つフラットな cdecl 関数を公開します

ビルド出力

build-HotPDF-ABI.cmd を実行すると、Lib/ABI/<platform>/Release の下に Win32 と Win64 の DLL とインポートライブラリがビルドされます

公開 ABI は安定した小文字のエクスポート名を使用し、hpdf_abi_version と hpdf_abi_io_v1_size を使用して、呼び出し側はドキュメントを作成する前に契約を検証できます

コア関数

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

バージョン管理された I/O 構造

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 で 48 バイト、Win64 で 72 バイトで、flags は ABI v1 ではゼロでなければならず、より大きな将来の構造体はフィールドレイアウトを推測せずに区別できます

すべてのコールバックとエクスポート関数は cdecl を使用し、すべてのテキストポインタには明示的なバイト長があり、Delphi の文字列、クラス、インターフェイス、列挙、例外、Boolean は境界を越えません

ランダムアクセス入力

read_at は絶対 64 ビットオフセットを受け取り、パーサーの宛先バッファに直接書き込みます。get_size はソースが接続されたときに不変のソースサイズを一度報告します

部分的な成功した読み取りは受け入れられ、繰り返しのコールバック呼び出しで完了するため、レンジストアと境界付きネットワークリーダーは中間の完全なファイルバッファを割り当てる必要がありません

コールバック状態とソースバイトは、ドキュメントハンドルが破棄されるか、別のソースがハンドルに読み込まれるまで有効なままでなければなりません

ストリーム出力

write は SaveLoadedDocumentToStream からの連続出力チャンクを直接受け取ります。部分的な成功した書き込みは、チャンク全体が受け入れられるまで再試行されます

ゼロバイトの成功した書き込みは前方に進めないため、I/O エラーとして拒否されます

JSON execute や 2 ハンドル比較の操作では、書き込みコールバックが失敗したとき、同じ writer と user-data のペアを通じてエラー結果を公開するためにコールバックが再度呼ばれることはありません。OutputIO と ResultIO がそのペアを共有している場合も同様です。呼び出し側がすでに受け取った部分的な候補バイトは、呼び出し側の責任で処理します

定義された非ゼロステータス範囲外の書き込みステータスや、ゼロまたは過大な成功バイト数は HPDF_STATUS_IO_ERROR になります。V1 のレコードレイアウトと部分的な成功書き込みの動作は変更されません

ステータスとライフサイクル

成功した hpdf_document_create には成功した hpdf_document_destroy を 1 回対応させる必要があります。繰り返しの破棄は HPDF_STATUS_INVALID_HANDLE を返します

不透明ハンドルはオブジェクトアドレスではなく単調なプロセスローカルトークンであるため、アロケータの再利用が古いハンドルを生き返らせることはありません

例外は C の境界を越えることはなく、オプションの診断コールバックは操作がエラーステータスを返す前に、対応するメッセージバイトを受け取ります

並行性

異なるハンドルは並行して使用できますが、呼び出し側は同じハンドルに対する操作と破棄を直列化する必要があります

レガシー Pascal コールバック

THPDFABICallbacks と HPDFDoc* Pascal ヘルパーは Delphi と C++Builder アプリケーションに対してソース互換のままですが、ネイティブ C 統合は hotpdf_abi.h と小文字の v1 エクスポートを使用する必要があります