Operações de documentos 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, retendo a continuidade entre páginas, as células unidas e a 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 nativas de exportação 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 (predefinido); a exportação de tabelas aceita csv (predefinido), json e xlsx

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

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

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

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

dateOrder aceita ymd (predefinido), mdy e dmy; os separadores têm de ser caracteres imprimíveis individuais, e um thousandsSeparator vazio desativa-o

minimumTableConfidence aceita valores de 0 a 1 e assume 0,55 por predefinição; um columnTolerance positivo assume 12 unidades de página por predefiniçã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 pedidos são limitados por orçamentos conservadores de memória e de objetos

A preparação da exportação fica limitada ao menor entre budget.outputBytes e um quarto de budget.memoryBytes; o effectiveOutputLimit reporta esse teto, podendo aplicar-se um options.maxOutputBytes mais apertado

As falhas de recursos nativos reportam budget-exceeded, a métrica nativeExportResources e o diagnóstico nativo; observed=1 com limit=0 indica uma condição de recurso negado, e não utilização de bytes medida

Ambas as operações reportam documentUpdated: false, preservam as definições de arranque automático e de descodificação da fonte, preparam a saída antes da publicação e mantêm os destinos de ficheiro existentes após um trabalho de ficheiro falhado

As verificações de prazo e de cancelamento de callbacks ABI são cooperativas nos pontos de verificação de operação e de publicação; os tokens de cancelamento nativos também se aplicam dentro das fases de extração suportadas, e o trabalho nativo não é interrompido à força

THPDFJobProcessor.ExecuteLoadedOperation e hpdf_document_execute_json_v1 partilham o mesmo motor de operações de documentos versionado por schema

Descubra os nomes das operações atuais, os formatos, o perfil de assinatura, o comportamento dos callbacks e os orçamentos predefinidos com THPDFJobProcessor.Capabilities ou hpdf_capabilities_json_to_io

Operações

O JSON de operações usa UTF-8 e schemaVersion: 1; os índices de páginas começam em zero e as matrizes de páginas selecionadas não podem conter duplicados

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

Trabalhos OCR externos aceitam motores Tesseract CLI/DLL e RapidOCR CLI/DLL explicitamente configurados, além do valor por defeito ASCII incorporado, com definições tipadas, timeouts de motores, tetos de píxeis e publicação atómica

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

Assinatura PFX incremental aceita uma fonte retida não modificada, incluindo PDFs encriptados suportados com uma password de operação explícita, valida todos os CMS antigos e novos, preserva bytes e encriptação originais, suporta um campo vazio existente, verifica permissões de encriptação, e rejeita aliases de ficheiros de origem/saída

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

Conversão raster PDF/A-4 para arquivamento

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

Coloque este objeto na matriz operations de um trabalho de ficheiro, ou forneça-o diretamente através de hpdf_document_execute_json_v1 com um handle carregado e callbacks de saída binária; a C ABI ignora os caminhos de entrada/saída do trabalho de ficheiro e usa os seus adaptadores

acceptInformationLoss tem de ser o booleano JSON true, e iccProfileFile tem de nomear um caminho não vazio e sem NUL para um perfil ICC sRGB matrix/TRC suportado no anfitrião de execução; os caminhos relativos de perfis resolvem-se face ao diretório de trabalho do processo

dpi assume 150 por predefinição e aceita inteiros de 36 a 1200; a conversão cobre todas as páginas da fonte e rejeita qualquer membro pages

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

archive.lossy é true, e todas as flags em archive.lossProfile são false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances e structureIdentity

O conteúdo da página passa a píxeis RGB; as anotações e as aparências de widgets são omitidas, e as assinaturas originais não são transportadas para a saída. A fonte carregada permanece disponível com documentUpdated: false, incluindo após publicação falhada; as suas definições anteriores de arranque, descodificação, limiar de stream, cancelamento e renderização são restauradas

A saída binária é obrigatória, e a validação nativa PDF/A-4 tem de ser bem-sucedida antes da entrega. Para os limites de renderização, cor, codec, alias de fonte e conformidade, veja conversão raster PDF/A-4 de documentos carregados

Orçamentos de recursos de arquivamento

O objeto options opcional aceita inteiros exatos positivos que apertam os seguintes tetos efetivos; chaves desconhecidas e valores que excedam um teto rejeitam o pedido, em vez de aumentar o orçamento da operação

O ficheiro ICC fica limitado ao menor entre 4 MiB e memoryBytes / 16 antes da alocação; estas margens conservadoras cobrem preparação simultânea, buffers de saída, dados de imagem e trabalho do descodificador, e não estabelecem um limite estrito de RSS do processo

Aumente os orçamentos de topo do trabalho quando uma carga de arquivamento maior for intencional; as opções aninhadas apenas apertam os tetos efetivos, e os máximos nativos continuam a aplicar-se

Os pontos de verificação de arquivamento sondam o cancelamento dos callbacks, o token de cancelamento da fonte emprestada, o tempo decorrido e as contagens de objetos durante a conversão. As falhas de orçamento e de cancelamento mantêm os seus códigos de estado estruturados em todo o conversor nativo

Trabalhos de ficheiro

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

THPDFJobProcessor.Execute aceita uma matriz de operações, até 1024 operações e 4 MiB de JSON; os trabalhos existentes de fusão, divisão, otimização, encriptação e validação continuam disponíveis

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

Os artefactos são escritos num ficheiro temporário junto ao destino, descarregados e validados, e depois publicados atomicamente; a falha preserva um destino existente, e entrada/saída podem partilhar um caminho

Contrato de callbacks C

Inicialize hpdf_operation_v1 a zero, 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 transporta bytes JSON e um comprimento exato, entrada opcional de acesso aleatório, saída binária sequencial opcional e saída obrigatória sequencial do resultado JSON

Os callbacks de entrada, os dados do utilizador e os bytes PDF de suporte têm de permanecer válidos até o handle ser substituído ou destruído, porque o parsing preguiçoso retém o adaptador

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

Os callbacks usam cdecl, as transferências parciais são repetidas, e as escritas bem-sucedidas têm de progredir; as exceções são convertidas em códigos de estado fixos

As mutações só são aplicadas depois de a entrega do artefacto e do resultado JSON serem bem-sucedidas; falha ou cancelamento de callback faz rollback das alterações, e quem chama descarta os bytes já entregues

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

Orçamentos

O objeto de orçamento opcional aceita inteiros exatos positivos não superiores a 9007199254740991

Os orçamentos gerais de saída/resultado ficam cada um limitado a metade do orçamento de memória; a conversão de arquivamento aplica os tetos mais estritos acima. Estes valores limitam os recursos configurados da operação, e não a memória total do processo

As verificações de cancelamento e de tempo decorrido são cooperativas nos pontos de verificação de operação, página, leitura de entrada e escrita de saída; uma rotina nativa longa pode continuar até ao próximo ponto de verificação

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