Operações de Documento JSON e C ABI

export.structured exporta as páginas selecionadas como HTML, XHTML, XML ou JSON semânticos; tables.export exporta tabelas tipadas como CSV, JSON ou XLSX, preservando continuidade entre páginas, células mescladas e inferência nativa de valores

Ambas as operações exigem um destino de saída binário, preservam o documento e os campos de assinatura existentes e expõem opções de exportação nativas limitadas

Exportações estruturadas e de tabelas tipadas

{"schemaVersion":1,"type":"export.structured","pages":[0,1],"format":"html",
 "options":{"imageMode":"metadata","includeFormControls":false}}

{"schemaVersion":1,"type":"tables.export","pages":[0,1],"format":"json",
 "options":{"mergeAcrossPages":true,"dateOrder":"dmy",
            "decimalSeparator":",","thousandsSeparator":"."}}

A exportação estruturada aceita html, xhtml, xml e json (padrão); a exportação de tabelas aceita csv (padrão), json e xlsx

As opções Boolean estruturadas são includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations e includeFormControls; todas assumem true por padrão

imageMode aceita omit, metadata e embedded-png (padrão); veja Structured Loaded-Page Export para o modelo semântico e o comportamento de campos sensíveis

As opções estruturadas de recursos são maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes e maxTotalImageBytes

As opções Boolean de tabelas são detectMergedCells, detectRepeatedHeaders, mergeAcrossPages e inferValueTypes; todas assumem true por padrão

dateOrder aceita ymd (padrão), mdy e dmy; os separadores devem ser caracteres imprimíveis individuais, e um thousandsSeparator vazio o desabilita

minimumTableConfidence aceita de 0 a 1 e assume 0,55 por padrão; columnTolerance positivo assume 12 unidades de página por padrão

As opções de recursos de tabelas são maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters e maxOutputBytes; veja Extração de tabelas tipadas para o modelo de células

Nomes de opções desconhecidos, tipos inválidos, formatos não suportados e limites não positivos são rejeitados; os limites nativos solicitados são limitados por orçamentos conservadores de memória e de objetos

O staging de exportação é limitado ao menor entre budget.outputBytes e um quarto de budget.memoryBytes; effectiveOutputLimit relata esse teto, e um options.maxOutputBytes mais restritivo pode se aplicar

Falhas de recursos nativos relatam budget-exceeded, a métrica nativeExportResources e o diagnóstico nativo; observed=1 e limit=0 denotam uma condição de recurso negado, e não um uso de bytes medido

Ambas as operações relatam documentUpdated: false, preservam as configurações de auto-launch e de decodificação da origem, preparam a saída antes da publicação e mantêm destinos de arquivo existentes após um job de arquivo com falha

As checagens de prazo e de cancelamento de callbacks da ABI são cooperativas nos checkpoints de operação e de publicação; tokens de cancelamento nativos também valem dentro dos estágios de extração suportados, e o trabalho nativo não é interrompido à força

THPDFJobProcessor.ExecuteLoadedOperation e hpdf_document_execute_json_v1 compartilham o mesmo mecanismo de operações de documento com versão de schema

Descubra os nomes de operação atuais, os formatos, o perfil de assinatura, o comportamento de callbacks e os orçamentos padrão com THPDFJobProcessor.Capabilities ou hpdf_capabilities_json_to_io

Operações

O JSON de operação usa UTF-8 e schemaVersion: 1; os índices de página são base zero, e os arrays de páginas selecionadas não podem conter duplicatas

A substituição de texto retorna um status parcial quando a API nativa de substituição não consegue codificar uma correspondência; inspecione as contagens por página dela

Jobs de OCR externos aceitam engines Tesseract CLI/DLL e RapidOCR CLI/DLL explicitamente configuradas além do default ASCII embutido, com configurações tipadas, timeouts de engines, limites de pixels e publicação atômica

As mutações rejeitam documentos com campos de assinatura existentes, incluindo placeholders não assinados; use o profile de assinatura incremental ou as APIs nativas incrementais para preservar assinaturas nesses documentos

Assinatura incremental com PFX aceita uma origem retida não modificada, incluindo PDFs criptografados suportados com uma password de operação explícita, valida todo CMS antigo e novo, preserva bytes originais e a encryption, suporta um campo vazio existente, confere permissões de encryption e rejeita aliases de arquivo de origem/saída

A assinatura produz um artefato assinado e restaura o handle original, relatando documentUpdated: false; os campos de formulário existentes permanecem disponíveis, os campos de assinatura temporários são removidos, e o handle pode ser consultado ou usado para outra operação após a assinatura

Conversão de arquivamento raster PDF/A-4

{
  "schemaVersion": 1,
  "type": "archive.pdfa4.raster",
  "acceptInformationLoss": true,
  "iccProfileFile": "profiles/sRGB.icm",
  "dpi": 150,
  "input": "source.pdf",
  "output": "archive.pdf"
}

Coloque este objeto no array operations de um job de arquivo, ou forneça-o diretamente por meio de hpdf_document_execute_json_v1 com um handle carregado e callbacks de saída binários; a ABI C ignora os caminhos de entrada/saída do job de arquivo e usa os adaptadores dela

acceptInformationLoss deve ser o Boolean JSON true, e iccProfileFile deve nomear um caminho não vazio e sem NUL para um perfil ICC sRGB matrix/TRC suportado na máquina de execução; caminhos de perfil relativos resolvem contra o diretório de trabalho do processo

dpi assume 150 por padrão e aceita inteiros de 36 a 1.200; a conversão cobre todas as páginas da origem e rejeita qualquer membro pages

O objeto de resultado archive relata nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields e removedEmbeddedFiles

archive.lossy é true, e cada flag em archive.lossProfile é false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances e structureIdentity

O conteúdo da página vira pixels RGB; anotações e aparências de widgets são omitidas, e assinaturas originais não são levadas para a saída. A origem carregada permanece disponível com documentUpdated: false, inclusive após uma publicação com falha; as configurações anteriores de abertura, decodificação, limite de stream, cancelamento e renderização são restauradas

Saída binária é obrigatória, e a validação nativa PDF/A-4 deve ter sucesso antes da entrega. Para os limites de renderização, cor, codec, alias de origem e conformidade, veja conversão raster PDF/A-4 de documento carregado

Orçamentos de recursos de arquivamento

O objeto options opcional aceita inteiros exatos positivos que restringem os tetos efetivos a seguir; chaves desconhecidas e valores que excedem um teto rejeitam a solicitação, em vez de ampliar o orçamento da operação

O arquivo ICC é limitado ao menor entre 4 MiB e memoryBytes / 16 antes da alocação; essas margens conservadoras cobrem staging simultâneo, buffers de saída, dados de imagem e trabalho do decoder, e não estabelecem um limite rígido de RSS do processo

Aumente os orçamentos de job de nível superior quando uma carga maior de arquivamento for intencional; opções aninhadas apenas restringem os tetos efetivos, e os máximos nativos continuam valendo

Os checkpoints de arquivamento consultam o cancelamento de callbacks, o token de cancelamento da origem emprestada, o tempo decorrido e as contagens de objetos durante a conversão. Falhas de orçamento e de cancelamento preservam os códigos de status estruturados no conversor nativo

Jobs de arquivo

{
  "operations": [
    {"type": "capabilities"},
    {"schemaVersion": 1, "type": "text.extract", "input": "input.pdf",
     "pages": [0, 1], "output": "text.txt"}
  ]
}

THPDFJobProcessor.Execute aceita um array de operações, até 1.024 operações e 4 MiB de JSON; os jobs existentes de mesclagem, divisão, otimização, criptografia e validação continuam disponíveis

Cada operação de documento fornece um caminho de entrada e uma senha opcional; render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign e archive.pdfa4.raster exigem um caminho de saída

Os artefatos são gravados em um arquivo temporário ao lado do destino, passam por flush e validação e depois são publicados atomicamente; uma falha preserva um destino existente, e entrada/saída podem compartilhar um caminho

Contrato de callbacks C

Inicialize hpdf_operation_v1 com zeros, defina struct_size com o tamanho nativo, abi_version com HPDF_ABI_VERSION_1 e as flags com zero; compare o tamanho com hpdf_abi_operation_v1_size

O record de operação carrega os bytes JSON e um comprimento exato, uma entrada opcional de acesso aleatório, uma saída binária sequencial opcional e uma saída sequencial obrigatória de resultado JSON

Os callbacks de entrada, os dados do usuário e os bytes do PDF de origem devem permanecer válidos até que o handle seja substituído ou destruído, porque o parsing lazy retém o adaptador

Os callbacks de saída/resultado existem apenas durante a chamada; serialize as chamadas para cada handle e evite reentrância de callbacks

Os callbacks usam cdecl, transferências parciais são repetidas e gravações bem-sucedidas devem progredir de forma positiva; exceções são convertidas em códigos de status fixos

As mutações só fazem commit depois que a entrega do artefato e do resultado JSON tem sucesso; falha ou cancelamento de callback faz rollback das mudanças, e os chamadores descartam quaisquer bytes já entregues

A entrada de substituição é carregada antes da transação de mutação e permanece uma mudança de estado separada

Orçamentos

O objeto budget opcional aceita inteiros exatos positivos não maiores que 9.007.199.254.740.991

Os orçamentos gerais de saída/resultado são cada um limitados à metade do orçamento de memória; a conversão de arquivamento aplica os tetos mais rígidos acima. Eles limitam os recursos configurados da operação, e não a memória total do processo

As checagens de cancelamento e de tempo decorrido são cooperativas nos checkpoints de operação, página, leitura de entrada e escrita de saída; uma rotina nativa longa pode continuar até o próximo checkpoint

Os relatórios carregam schemaVersion, status e statusCode; erros de orçamento usam status 8, cancelamento 4, falha de I/O 5, falha de parsing 6, argumentos inválidos 1 e falha de execução 7