THPDFHeadlessDocument
HPDFHeadlessDocument provee una API de documentos de consola para Linux y Windows nativos usando el parser de objetos existente de HotPDF, los helpers de Direct File, los decodificadores de fuentes, el intérprete de contenido, los decodificadores de filtros y el writer de xref
El loader de documentos acepta tablas de referencias cruzadas clásicas, xref streams, secciones xref híbridas, cadenas incrementales Prev, objetos directos y comprimidos, recursos de página heredados, arrays de contenido, Form XObjects y árboles de campos AcroForm
Los side streams híbridos tienen precedencia sobre la tabla que los acompaña, mientras que las revisiones más nuevas tienen precedencia sobre las más viejas; los miembros de object-streams se decodifican y parsean de forma perezosa mediante el parser de objetos compartido
Ciclo de vida y ownership
Create usa THPDFHeadlessDocumentOptions.Default, mientras que el overload de opciones acepta presupuestos explícitos y un cancellation token propio del caller
LoadFromFile cierra el documento anterior, abre la fuente en solo lectura, carga el object graph actual y cierra el estado parcial ante fallos; Close libera la fuente y todos los objetos cargados
LoadFromFile(FileName, Password) autentica documentos Standard AES-256 R5 o R6 mediante THPDFHeadlessAES256Security; el overload original de un solo argumento usa un password vacío
Los user passwords deben conceder extracción de texto o llenado de formularios antes de que esas operaciones se ejecuten, mientras que los owner passwords omiten las restricciones de permisos de usuario; los passwords incorrectos, los mismatches de Perms autenticados, las operaciones denegadas y los payloads de cifrado malformados tienen diagnósticos de documento distintos
Las cadenas y streams directos se descifran mediante el código criptográfico compartido, los miembros comprimidos se descifran junto con su contenedor únicamente, y los reemplazos incrementales cifrados permanecen cifrados bajo las claves y la política de permisos originales
Los passwords usan bytes UTF-8 truncados a 127 bytes sin normalización SASLprep; los handlers no soportados, los Crypt filters explícitos y las políticas PDF MAC se diagnostican en lugar de ignorarse
Las claves de diccionarios codificadas y los nombres de recursos se decodifican antes de usarse, las mayúsculas siguen siendo significativas y las claves decodificadas duplicadas se rechazan; los flags de campos y MaxLen deben caber en el rango no negativo de 32 bits soportado
Las instancias no son thread-safe; usa una instancia por worker y mantén vivo su cancellation token hasta que la instancia se destruya
Páginas y texto
PageCount reporta el número de hojas del árbol de páginas; ExtractPageText(PageIndex) acepta un índice con base cero y devuelve texto Unicode ensamblado por el intérprete de glifos compartido
ExtractPageTextBounded aplica límites temporales de glifos y streams antes de preparar el texto y restaura todas las opciones originales de recursos tras el éxito, el fallo o la cancelación
GetObjectAccess expone acceso prestado de solo lectura al catalog, la información y los objetos, con asignación de índices acotada para la comparación nativa estructural y full
La decodificación de texto sigue las codificaciones de fuentes, las diferencias de codificación, los CMaps ToUnicode incrustados, los anchos explícitos y el proveedor de métricas de fuentes estándar; los Form XObjects anidados aplican sus matrices y usan sus diccionarios de recursos propios o heredados
El fallback de fuentes estándar de Linux exige Fontconfig y fuentes TrueType instaladas; las fuentes complejas de documentos deben proveer una estrategia de decodificación soportada, y los recursos de fuentes ausentes producen un diagnóstico
AppendPageText agrega texto Unicode visible o invisible ajustado mientras retiene el contenido original de la página y las políticas de seguridad cifradas
AppendImportedPages clona los graphs de recursos de páginas seleccionados, la geometría heredada y las apariencias normales visibles mientras preserva las revisiones de destino existentes y la política de cifrado autenticada
Valores de texto AcroForm
FormFieldCount, GetFormField(FieldIndex) y FindFormField(Name) enumeran los campos terminales usando nombres completamente calificados y tipos, flags, longitudes máximas y valores heredados; los índices son con base cero, y un nombre ausente devuelve -1
SetTextFieldValue(FieldIndex, Text) acepta campos Tx escribibles, escribe una cadena PDF UTF-16BE y fija NeedAppearances=true en el diccionario AcroForm
Este método de solo valor depende de la regeneración del visor; los visores que no regeneran apariencias pueden seguir mostrando una apariencia vieja o un widget vacío
SetTextFieldValueWithAppearance genera apariencias Unicode explícitas para cada widget existente usando una fuente TrueType aportada por el caller, métricas reales de glifos, codificación Identity-H, ToUnicode e incrustación completa de FontFile2
El perfil de apariencias soporta texto de una línea y multilínea, ajuste de línea, celdas comb, rotaciones de cuarto de vuelta, tamaño fijo o auto-fit, alineación y shaping complejo opcional nativo con HarfBuzz/FriBidi
SetChoiceFieldValuesWithAppearance maneja list boxes de selección múltiple, opciones heredadas, arrays de exportación ordenados y cada fila visible seleccionada; el helper de valor único también soporta etiquetas de export/visualización de combos
GetChoiceFieldValues lee el array completo de exportación seleccionada; SetButtonFieldValueWithAppearance y SetPushButtonAppearance generan estados y captions reales de botones
Los objetos y streams de apariencias nuevos se acotan antes de cambiar los campos y permanecen cifrados bajo la política de seguridad AES original al guardar; el Cairo nativo de Linux y los lectores independientes consumen los mismos objetos generados
Los campos read-only, los valores más largos que MaxLen en unidades de código UTF-16, los campos que no son de texto, los formularios XFA, los campos firmados y los permisos de documentos certificados se rechazan para edición
Los documentos firmados usan políticas autenticadas DocMDP y FieldMDP: las actualizaciones de formularios permitidas preservan las revisiones firmadas existentes, mientras que los campos bloqueados, las restricciones P1 y los intentos de sobrescribir campos de firma firmados se rechazan
La evidencia DSS/VRI validada agrega datos autenticados de certificados y revocación a una revisión incremental sin cambiar las firmas ByteRange existentes
Verificación de firmas
SignatureCount enumera los campos de firma AcroForm firmados y VerifySignature(SignatureIndex, Options) valida firmas con base cero usando el parser compartido y el proveedor CMS OpenSSL 3 en streaming
El perfil PDF acepta adbe.pkcs7.detached y ETSI.CAdES.detached reconocidos automáticamente con Contents hexadecimales o literales estándar; CAdES siempre autentica el binding ESS de certificado de firmante, mientras que los ajustes explícitos de CA evalúan el trust por separado
DocTimeStamp con ETSI.RFC3161 autentica automáticamente el TSTInfo encapsulado genuino, el ESS, el propósito TSA y el nombre del firmante, y el imprint PDF exacto; las roots y CRLs de timestamps configuradas evalúan el trust del TSA por separado
La verificación valida el gap sin firmar exacto incluidos sus delimitadores y vincula sus bytes decodificados al diccionario de firma actual antes de la verificación criptográfica
El resultado distingue la integridad, el trust de CA explícitamente evaluado y los bytes sin firmar tras la revisión autenticada; los perfiles de firmas PDF no soportados producen un diagnóstico tipado
Consulta HPDFVerifyHeadlessCMS para los requisitos de runtime y THPDFHeadlessCMSOptions para los presupuestos y ajustes de trust
Firmas de aprobación incrementales
SignToFile firma un campo Sig existente, escribible y sin firmar, y publica un PDF independientemente actualizado de forma incremental usando un certificado PEM aportado por el caller y una clave privada PEM sin cifrar
AddSignatureField crea un widget de página y sus links AcroForm, incluido un AcroForm nuevo sobre un PDF importado plano; SetSignatureFieldAppearance genera su caption visible, y SignPFXToFile carga una identidad certificado/clave PKCS12 con su cadena
CertificationPermission crea la primera firma de certificación DocMDP; P2 y P3 permiten firmas de aprobación posteriores en campos existentes, mientras que P1 rechaza más firmas
Los bytes fuente originales y el object graph cargado quedan sin cambios; las firmas de aprobación posteriores preservan los bytes de firmas anteriores y sus límites autenticados de revisión
El cifrado Standard AES-256 R5 y R6, los passwords, los IDs y los permisos siguen en vigor, incluidas las fuentes de object-streams cifradas; la cadena Contents de la firma sigue la exención de cifrado del PDF
Los valores de firmas existentes, los campos read-only, las políticas de documentos certificados, los permisos de form-fill denegados, los cancellation tokens divergentes y los presupuestos de salida agotados se rechazan sin publicar una salida
Timestamps de documento
TimestampToFile crea un timestamp de documento RFC 3161 genuino en un campo de firma existente sin firmar, sin clave de firma de la aplicación, usando un transporte TSA propio del caller y trust TSA explícito
El writer preserva las revisiones originales y la seguridad AES, declara la extensión ESIC para entradas anteriores a PDF 2.0, y publica atómicamente solo cuando las comprobaciones de nonce, imprint, firma, certificado, revocación configurada y seeds pasan
Los cambios autenticados necesarios de timestamps de documento se permiten bajo DocMDP y FieldMDP; las ediciones ordinarias de formularios y las firmas de aprobación retienen sus restricciones originales
Intercambio de formularios FDF y XFDF
ExportAnnotationsFDF exporta grafos de objetos de anotaciones acotados y sus recursos de apariencia compartidos; SaveAnnotationsFDFToFile prepara reemplazos con nombre y adiciones en una revisión incremental atómica independiente
El perfil binario FDF de anotaciones preserva la política de cifrado y firmas del documento autenticado, referencias de página GoTo locales sensibles al contexto y publicación exacta sin cambios; deja el documento cargado sin cambios tras el éxito y el fallo
SaveAnnotationsXFDFToFile agrega anotaciones mapeadas acotadas a una revisión incremental independiente; HPDFExportHeadlessAnnotationsXFDF devuelve sus bytes XFDF
ExportFormData devuelve datos de campos Unicode acotados, incluidos arrays de choice reales y estados de exportación de checkbox o radio
ImportFormDataToFile regenera apariencias genuinas sobre un graph de revisión privado autenticado y publica atómicamente un PDF incremental preservando el estado de la fuente cargada
ImportRichFormDataToFile importa el perfil XHTML acotado desde FDF RV o XFDF value-richtext con programas de fuente reales regular, bold, italic y bold-italic
SaveRichTextFieldUpdatesToFile aplica campos escalares y runs rich tipados originales en una revisión atómica independiente, preservando los programas de fuente reales y la precisión numérica PDF; los campos protegidos sin cambios exigen apariencias decodificadas y recursos resueltos coincidentes para cada widget
El cifrado existente, los flags read-only, los DocMDP y FieldMDP autenticados, las firmas originales, la cancelación y los presupuestos de recursos siguen haciéndose cumplir; consulta form data nativo FDF y XFDF para la sintaxis soportada y los límites del intercambio escalar
Acceso prestado de rendering
GetRenderAccess(PageIndex) provee el diccionario de página existente, los recursos heredados, el resolver de fuentes, la resolución de objetos, la comprobación de permisos, el cancellation token y los callbacks acotados de streams decodificados mediante THPDFHeadlessRenderAccess
Esta es una vista prestada serial de solo lectura; el documento debe permanecer cargado y sin cambios hasta que el renderer termine, y los callers no deben mutar su object graph expuesto
El callback RequireOutputPath de la vista comprueba una salida prospectiva contra el path canónico de la fuente y la identidad física del archivo sin crear ni modificar archivos
Salida independiente
ExtractPageGlyphs devuelve glifos posicionados mediante el walker acotado de contenido anidado; AnalyzePageSemanticText provee texto semántico y geometría de fuente para la comparación nativa de contratos
SaveToFile(FileName) copia los bytes originales y agrega valores de objetos de reemplazo, una tabla xref clásica y un trailer vinculado mediante Prev; los miembros de objetos comprimidos se materializan como objetos directos en la revisión agregada, y los bytes de streams originales se preservan
La salida no debe ser alias del path o de la identidad de archivo de la fuente; la escritura usa un archivo de staging creado en exclusiva en el directorio de destino, le hace flush y lo publica mediante rename atómico
Los fallos de presupuesto, cancelación o serialización preservan un destino existente y eliminan el archivo de staging no publicado; la fuente permanece en solo lectura
El PDF de revisión anotado nativo exporta highlights Unicode reales y apariencias visibles con permisos autenticados de anotaciones, reteniendo el documento cargado original y las revisiones de firmas
Límites de formato
El perfil actual soporta cifrado Standard AES-256 R5 y R6, diagnostica explícitamente los security handlers y stream filters no soportados, y rechaza las generaciones retiradas de free-objects que su writer no puede representar
Los xref streams de bootstrap exigen valores de diccionario directos y un Length directo acotado; los anchos malformados, los solapamientos de subsecciones, los offsets sin signo sobre Int64, los mismatches de miembros comprimidos, los ciclos de referencias y los límites configurados producen diagnósticos tipados
El contenido decodificado soporta los filtros Flate, ASCIIHex, ASCII85 y LZW con predictors soportados y longitudes de stream indirectas; los payloads de imágenes no se decodifican para la extracción de texto
Los workflows nativos de firma cubren campos de firma, apariencias visibles y certificación; las políticas autenticadas de formularios firmados y las APIs de timestamp y validación a largo plazo retienen sus opciones explícitas de integridad y trust
Aceptación
Las familias de fuentes rich nombradas agregan múltiples familias reales suministradas mediante SetRichTextFieldValueWithFamilies e ImportRichFormDataWithFamiliesToFile, con las políticas existentes de campos, seguridad y transacciones
Los campos rich text nativos proveen runs con estilo tipados, apariencias reales con fuentes de estilo incrustadas, valores V y RV sincronizados, salida incremental cifrada y ediciones transaccionales acotadas; GetRichTextFieldValue lee el XHTML almacenado o heredado
Tests/Linux/Run-HeadlessDocumentTests.sh compila un ejecutable ELF nativo con las variables de escritorio limpiadas y comprueba las dependencias de bibliotecas GUI; Run-HeadlessDocumentTests-Windows.cmd Win32 y Win64 ejercitan la misma API compartida de documentos
Consulta THPDFHeadlessFormField, EHPDFHeadlessDocumentError y THPDFHeadlessDiagnosticCode para los valores devueltos y los diagnósticos tipados
Eliminación de anotaciones
Elimine anotaciones de página por identidad exacta de página y NM Unicode mediante SaveAnnotationRemovalsToFile, con cascadas de popups y respuestas, preparación acotada y salida separada atómica
El documento cargado permanece sin cambios; una selección sin cambios copia la revisión actual exacta, y la eliminación incremental retiene los bytes históricos