Operaciones de documentos JSON y C ABI

export.structured exporta las páginas seleccionadas como HTML, XHTML, XML o JSON semánticos; tables.export exporta tablas tipadas como CSV, JSON o XLSX, conservando la continuidad entre páginas, las celdas combinadas y la inferencia de valores nativa

Ambas operaciones requieren un destino de salida binario, preservan el documento y los campos de firma existentes, y exponen opciones nativas de exportación acotadas

Exportaciones estructuradas y de tablas 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":"."}}

La exportación estructurada acepta html, xhtml, xml y json (predeterminado); la exportación de tablas acepta csv (predeterminado), json y xlsx

Las opciones booleanas estructuradas son includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations y includeFormControls; todas quedan en true de forma predeterminada

imageMode acepta omit, metadata y embedded-png (predeterminado); vean Exportación estructurada de páginas cargadas para el modelo semántico y el comportamiento de los campos sensibles

Las opciones de recursos estructurados son maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes y maxTotalImageBytes

Las opciones booleanas de tablas son detectMergedCells, detectRepeatedHeaders, mergeAcrossPages e inferValueTypes; todas quedan en true de forma predeterminada

dateOrder acepta ymd (predeterminado), mdy y dmy; los separadores deben ser caracteres imprimibles individuales, y un thousandsSeparator vacío lo deshabilita

minimumTableConfidence acepta valores de 0 a 1 y queda en 0.55 de forma predeterminada; un columnTolerance positivo usa 12 unidades de página como valor predeterminado

Las opciones de recursos de tablas son maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters y maxOutputBytes; vean Extracción de tablas tipadas para el modelo de celdas

Los nombres de opciones desconocidos, los tipos inválidos, los formatos no soportados y los límites no positivos se rechazan; los límites nativos solicitados se acotan con presupuestos conservadores de memoria y de objetos

El staging de exportación se limita al menor valor entre budget.outputBytes y un cuarto de budget.memoryBytes; effectiveOutputLimit reporta ese tope, mientras que un options.maxOutputBytes más estricto puede aplicarse además

Los fallos de recursos nativos reportan budget-exceeded, la métrica nativeExportResources y el diagnóstico nativo; observed=1 y limit=0 denotan una condición de recurso denegada, no un uso de bytes medido

Ambas operaciones reportan documentUpdated: false, preservan los ajustes de auto-launch y de decodificación del origen, llevan la salida por staging antes de publicarla y conservan los destinos de archivo existentes tras un job de archivos fallido

Las comprobaciones de cancelación por fecha límite y por callbacks del ABI son cooperativas en los puntos de control de operación y de publicación; los tokens de cancelación nativos también aplican dentro de las etapas de extracción que los soportan, y el trabajo nativo no se interrumpe a la fuerza

THPDFJobProcessor.ExecuteLoadedOperation y hpdf_document_execute_json_v1 comparten el mismo motor de operaciones de documento versionado por schema

Descubran los nombres de operaciones vigentes, los formatos, el perfil de firma, el comportamiento de callbacks y los presupuestos predeterminados con THPDFJobProcessor.Capabilities o hpdf_capabilities_json_to_io

Operaciones

El JSON de operación usa UTF-8 y schemaVersion: 1; los índices de página son base cero y los arrays de páginas seleccionadas no pueden contener duplicados

El reemplazo de texto devuelve un estado parcial cuando la API nativa de reemplazo no puede codificar una coincidencia; inspeccionen sus conteos por página

Los jobs OCR externos aceptan engines Tesseract CLI/DLL y RapidOCR CLI/DLL configurados explícitamente junto al default ASCII integrado, con settings tipados, timeouts de engine, caps de píxeles y publicación atómica

Las mutaciones rechazan documentos con campos de firma existentes, incluyendo placeholders sin firmar; use el perfil de firma incremental o las APIs incrementales nativas para preservar firmas en esos documentos

La firma incremental con PFX acepta una fuente retenida sin modificar, incluyendo PDFs cifrados soportados con una password de operación explícita, valida cada CMS viejo y nuevo, preserva los bytes y el cifrado originales, soporta un campo vacío existente, comprueba los permisos de cifrado y rechaza alias entre archivos de origen y salida

La firma produce un artifact firmado y restaura el handle original, reportando documentUpdated: false; los campos de formulario existentes siguen disponibles, los campos de firma temporales se eliminan y el handle puede consultarse o usarse para otra operación después de firmar

Conversión de archivado raster PDF/A-4

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

Coloquen este objeto en el array operations de un file job, o entréguenlo directamente mediante hpdf_document_execute_json_v1 con un handle cargado y callbacks de salida binaria; el C ABI ignora las rutas de entrada/salida del file job y usa sus adaptadores

acceptInformationLoss debe ser el booleano JSON true, y iccProfileFile debe nombrar una ruta no vacía y sin NUL hacia un perfil ICC sRGB matrix/TRC soportado en la computadora que ejecuta el proceso; las rutas de perfil relativas se resuelven contra el directorio de trabajo del proceso

dpi queda en 150 de forma predeterminada y acepta enteros de 36 a 1,200; la conversión cubre todas las páginas del origen y rechaza cualquier miembro pages

El objeto de resultado archive reporta nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields y removedEmbeddedFiles

archive.lossy es true, y cada flag en archive.lossProfile es false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances y structureIdentity

El contenido de la página se convierte en píxeles RGB; las anotaciones y las apariencias de widgets se omiten, y las firmas originales no se trasladan a la salida. El origen cargado sigue disponible con documentUpdated: false, incluso después de una publicación fallida; sus ajustes previos de lanzamiento, decodificación, umbrales de stream, cancelación y render se restauran

Se requiere salida binaria, y la validación nativa PDF/A-4 debe tener éxito antes de la entrega. Para los límites de render, color, codecs, alias de origen y conformidad, vean Conversión de PDF cargado a raster PDF/A-4

Presupuestos de recursos de archivado

El objeto options opcional acepta enteros exactos positivos que estrechan los siguientes topes efectivos; las claves desconocidas y los valores que exceden un tope rechazan la solicitud en lugar de aumentar el presupuesto de la operación

El archivo ICC se acota al menor valor entre 4 MiB y memoryBytes / 16 antes de la asignación; estos márgenes conservadores cubren staging simultáneo, buffers de salida, datos de imágenes y trabajo del decodificador, y no establecen un límite estricto de RSS del proceso

Aumenten los presupuestos de job de nivel superior cuando una carga de archivado mayor sea intencional; las opciones anidadas solo estrechan los topes efectivos, y los máximos nativos siguen aplicando

Los puntos de control de archivado consultan la cancelación de callbacks, el token de cancelación del origen prestado, el tiempo transcurrido y los conteos de objetos durante la conversión. Los fallos de presupuesto y de cancelación conservan sus códigos de estado estructurados a través del conversor nativo

Jobs de archivos

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

THPDFJobProcessor.Execute acepta un array de operaciones, hasta 1,024 operaciones y 4 MiB de JSON; los jobs existentes de merge, split, optimise, encrypt y validate siguen disponibles

Cada operación de documento suministra una ruta de entrada y una contraseña opcional; render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign y archive.pdfa4.raster requieren una ruta de salida

Los artifacts se escriben en un archivo temporal junto al destino, se vacían y validan, y luego se publican de forma atómica; un fallo preserva un destino existente, y entrada/salida pueden compartir una ruta

Contrato de callbacks C

Inicialicen hpdf_operation_v1 a cero, asignen a struct_size su tamaño nativo, a abi_version el valor HPDF_ABI_VERSION_1, y los flags a cero; comparen su tamaño con hpdf_abi_operation_v1_size

El record de operación transporta los bytes JSON y una longitud exacta, una entrada opcional de acceso aleatorio, una salida binaria secuencial opcional y una salida secuencial obligatoria del resultado JSON

Los callbacks de entrada, los datos de usuario y los bytes PDF de respaldo deben permanecer válidos hasta que el handle se reemplace o destruya, porque el parseo lazy retiene el adaptador

Los callbacks de salida/resultado existen solo durante la llamada; serialicen las llamadas de cada handle y eviten la reentrada de callbacks

Los callbacks usan cdecl, las transferencias parciales se reintentan, y las escrituras exitosas deben avanzar de forma positiva; las excepciones se convierten en códigos de estado fijos

Las mutaciones hacen commit solo después de que la entrega del artifact y del resultado JSON tenga éxito; un fallo o una cancelación de callback revierte los cambios, y los llamadores descartan cualquier byte ya entregado

La entrada de reemplazo se carga antes de la transacción de mutación y sigue siendo un cambio de estado separado

Presupuestos

El objeto de presupuesto opcional acepta enteros exactos positivos no mayores que 9,007,199,254,740,991

Los presupuestos generales de salida/resultado se acotan cada uno a la mitad del presupuesto de memoria; la conversión de archivado aplica los topes más estrictos de arriba. Estos valores acotan los recursos configurados de la operación, no la memoria total del proceso

Las comprobaciones de cancelación y de tiempo transcurrido son cooperativas en los puntos de control de operación, página, lectura de entrada y escritura de salida; una rutina nativa larga puede continuar hasta su siguiente punto de control

Los reportes transportan schemaVersion, status y statusCode; los errores de presupuesto usan status 8, cancelación 4, fallo de I/O 5, fallo de parseo 6, argumentos inválidos 1 y fallo de ejecución 7