ABI estável de retorno de chamada C do HotPDF

HotPDFABI.dll expõe funções planas cdecl com valores de status de largura fixa, identificadores opacos, comprimentos de byte explícitos e a estrutura de retorno de chamada versionada hpdf_io_v1 declarada em Lib/hotpdf_abi.h

Saídas de build

Execute build-HotPDF-ABI.cmd para compilar DLLs Win32 e Win64 além de bibliotecas de importação em Lib/ABI/<platform>/Release

A ABI pública usa nomes de exportação estáveis em minúsculas, enquanto hpdf_abi_version e hpdf_abi_io_v1_size permitem que os chamadores verifiquem o contrato antes de criar um documento

Funções principais

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

Estrutura de E/S versionada

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 é 48 bytes no Win32 e 72 bytes no Win64, flags deve ser zero para ABI v1 e estruturas futuras maiores podem ser distinguidas sem adivinhar o layout dos campos

Todos os retornos de chamada e funções exportadas usam cdecl, todo ponteiro de texto tem um comprimento de byte explícito e nenhuma string Delphi, classe, interface, enum, exceção ou Boolean cruza o limite

Entrada de acesso aleatório

read_at recebe um deslocamento absoluto de 64 bits e grava diretamente no buffer de destino do analisador, enquanto get_size relata o tamanho imutável da fonte uma vez quando a fonte é anexada

Leituras parciais bem-sucedidas são aceitas e concluídas por meio de chamadas repetidas de retorno de chamada, de modo que armazenamentos de intervalo e leitores de rede limitados não precisem alocar um buffer intermediário de arquivo completo

O estado do retorno de chamada e os bytes da fonte devem permanecer válidos até que o identificador do documento seja destruído ou outra fonte seja carregada no identificador

Saída em fluxo

write recebe blocos de saída sequenciais diretamente de SaveLoadedDocumentToStream; gravações parciais bem-sucedidas são repetidas até que o bloco completo seja aceito

Uma gravação bem-sucedida de zero bytes é rejeitada como erro de E/S porque não pode avançar

Para operações JSON execute e de comparação de dois handles, um callback de gravação que falhou não é chamado de novo para publicar um resultado de erro pelo mesmo par de writer e user-data, inclusive quando OutputIO e ResultIO compartilham esse par; os bytes candidates parciais já recebidos pelo chamador continuam sendo responsabilidade dele

Valores de status de gravação fora da faixa de status não zero definida, e contagens de bytes bem-sucedidos zero ou excessivas, tornam-se HPDF_STATUS_IO_ERROR; o layout do record V1 e o comportamento de partial write bem-sucedido permanecem inalterados

Status e ciclo de vida

Cada hpdf_document_create bem-sucedido deve ser emparelhado com um hpdf_document_destroy bem-sucedido; a destruição repetida retorna HPDF_STATUS_INVALID_HANDLE

Identificadores opacos são tokens monotônicos locais ao processo em vez de endereços de objeto, de modo que a reutilização do alocador não possa reviver um identificador obsoleto

Exceções nunca cruzam o limite C, e o retorno de chamada de diagnóstico opcional recebe os bytes da mensagem correspondente antes que uma operação retorne um status de erro

Concorrência

Identificadores diferentes podem ser usados simultaneamente, mas os chamadores devem serializar operações e destruição para o mesmo identificador

Retornos de chamada Pascal legados

THPDFABICallbacks e os auxiliares Pascal HPDFDoc* permanecem compatíveis com a fonte para aplicativos Delphi e C++Builder, mas integrações C nativas devem usar hotpdf_abi.h e as exportações v1 em minúsculas