THPDFHeadlessDocument
HPDFHeadlessDocument aporta una API de documento de consola para Linux y Windows nativos usando el parser de objetos existente de HotPDF, los helpers Direct File, los decodificadores de fuentes, el intérprete de contenido, los decodificadores de filtros y el escritor de xref
El loader de documentos acepta tablas de referencias cruzadas clásicas, streams xref, secciones xref híbridas, cadenas incrementales de 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 acompañante, mientras que las revisiones más nuevas tienen precedencia sobre las más antiguas; los miembros de object-stream se decodifican y analizan de forma perezosa mediante el parser de objetos compartido
Ciclo de vida y propiedad
Create usa THPDFHeadlessDocumentOptions.Default, mientras que la sobrecarga de opciones acepta presupuestos explícitos y un token de cancelación propiedad del llamador
LoadFromFile cierra el documento anterior, abre el origen en solo lectura, carga el grafo de objetos actual y cierra el estado parcial en caso de fallo; Close libera el origen y todos los objetos cargados
LoadFromFile(FileName, Password) autentica documentos Standard AES-256 R5 o R6 mediante THPDFHeadlessAES256Security; la sobrecarga original de un solo argumento usa un password vacío
Los passwords de usuario deben conceder extracción de texto o relleno de formularios antes de ejecutar esas operaciones, mientras que los passwords de propietario omiten las restricciones de permisos de usuario; los passwords incorrectos, los desajustes 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 solo junto a su contenedor, 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 filtros Crypt explícitos y las políticas PDF MAC se diagnostican en lugar de ignorarse
Las claves de diccionario 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 campo 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 token de cancelación hasta que la instancia se destruya
Páginas y texto
PageCount informa del número de hojas del árbol de páginas; ExtractPageText(PageIndex) acepta un índice basado en cero y devuelve texto Unicode ensamblado desde 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 catálogo, a la información y a los objetos con asignación acotada de índices para la comparación nativa estructural y completa
La decodificación de texto sigue las codificaciones de fuentes, las diferencias de codificación, los CMaps ToUnicode incrustados, las anchuras explícitas y el proveedor de métricas de fuentes estándar; los Form XObjects anidados aplican sus matrices y usan sus propios diccionarios de recursos o los heredados
El fallback de fuentes estándar de Linux exige Fontconfig y fuentes TrueType instaladas; las fuentes complejas de documentos deben aportar una estrategia de decodificación soportada, y los recursos de fuentes ausentes producen un diagnóstico
AppendPageText añade texto Unicode visible o invisible ajustado mientras retiene el contenido original de página y las políticas cifradas de seguridad
AppendImportedPages clona los grafos de recursos de página 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 totalmente cualificados y tipos de campo heredados, flags, longitudes máximas y valores; los índices parten de cero, y un nombre ausente devuelve -1
SetTextFieldValue(FieldIndex, Text) acepta campos Tx escribibles, escribe una cadena PDF UTF-16BE y activa 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 antigua o un widget vacío
SetTextFieldValueWithAppearance genera apariencias Unicode explícitas para cada widget existente usando una fuente TrueType suministrada por el llamador, 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 export 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 export seleccionado; SetButtonFieldValueWithAppearance y SetPushButtonAppearance generan estados y captions reales de botones
Los nuevos objetos y streams de apariencias se acotan antes de cambiar los campos y permanecen cifrados bajo la política de seguridad AES original al guardar; el Cairo de Linux nativo y los lectores independientes consumen los mismos objetos generados
Los métodos de campos de texto aplican los flags de solo lectura, MaxLen en unidades de código UTF-16 y el tipo de campo; los campos de choice y botones usan sus métodos de apariencia separados, mientras que los formularios XFA quedan fuera del perfil AcroForm de este cargador de documentos
Los documentos firmados usan políticas autenticadas DocMDP y FieldMDP: las actualizaciones de formulario 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 añade 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 las firmas basadas en 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 firma, mientras que los ajustes CA explícitos evalúan la confianza 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 la impronta exacta del PDF; las raíces y CRLs de timestamp configuradas evalúan por separado la confianza TSA
La verificación valida el hueco 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, la confianza CA explícitamente evaluada y los bytes sin firmar tras la revisión autenticada; los perfiles de firma PDF no soportados producen un diagnóstico tipado
Consulta HPDFVerifyHeadlessCMS para los requisitos de runtime y THPDFHeadlessCMSOptions para los presupuestos y ajustes de confianza
Firmas de aprobación incrementales
SignToFile firma un campo Sig existente, escribible y sin firmar y publica un PDF independentemente actualizado de forma incremental usando un certificado PEM aportado por el llamador 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 de 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 de origen originales y el grafo de objetos cargado permanecen intactos; las firmas de aprobación posteriores preservan los bytes de las firmas anteriores y sus bordes autenticados de revisión
El cifrado Standard AES-256 R5 y R6, los passwords, los IDs y los permisos siguen en vigor, incluidos los orígenes de object-stream cifrados; la cadena Contents de la firma sigue la exención de cifrado del PDF
Los valores de firmas existentes, los campos de solo lectura, las políticas de documentos certificados, los permisos de relleno de formularios denegados, los tokens de cancelación 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 llamador y una confianza TSA explícita
El escritor 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, impronta, firma, certificado, revocación configurada y seed pasan
Los cambios autenticados necesarios de timestamp 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
SaveAnnotationsXFDFToFile añade anotaciones mapeadas acotadas a una revisión incremental independiente; HPDFExportHeadlessAnnotationsXFDF devuelve sus bytes XFDF
ExportAnnotationsFDF exporta grafos de objetos de anotaciones acotados y sus recursos de appearance compartidos; SaveAnnotationsFDFToFile prepara reemplazos con nombre y añade en una revisión PDF atómica independiente
El perfil de anotaciones FDF binario preserva el cifrado y la política de firmas del documento autenticado, las referencias de página GoTo locales sensibles al contexto y la publicación exacta sin cambios; deja el documento cargado sin cambios tras guardar
ExportFormData devuelve datos de campo Unicode acotados, incluidos los arrays reales de choice y los estados de export de checkbox o radio
ImportFormDataToFile regenera apariencias genuinas sobre un grafo de revisión privado autenticado y publica atómicamente un PDF incremental mientras preserva el estado del origen cargado
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 única revisión atómica independiente, preservando los programas de fuente reales y la precisión numérica del PDF; los campos protegidos sin cambios exigen apariencias decodificadas y recursos resueltos coincidentes para cada widget
El cifrado existente, los flags de solo lectura, el DocMDP y FieldMDP autenticados, las firmas originales, la cancelación y los presupuestos de recursos siguen aplicándose; consulta datos de formulario nativos FDF y XFDF para la sintaxis soportada y los bordes del intercambio escalar
Acceso prestado de rendering
GetRenderAccess(PageIndex) proporciona el diccionario de página existente, los recursos heredados, el resolver de fuentes, la resolución de objetos, la comprobación de permisos, el token de cancelación y los callbacks acotados de streams decodificados mediante THPDFHeadlessRenderAccess
Es una vista prestada serial de solo lectura; el documento debe permanecer cargado e intacto hasta que el renderer termine, y los llamadores no deben mutar su grafo de objetos expuesto
El callback RequireOutputPath de la vista comprueba una salida prospectiva contra la ruta canónica del origen y la identidad física del fichero sin crear ni modificar ficheros
Salida independiente
ExtractPageGlyphs devuelve glifos posicionados mediante el walker acotado de contenido anidado; AnalyzePageSemanticText aporta texto semántico y geometría de origen para la comparación nativa de contratos
SaveToFile(FileName) copia los bytes originales y añade los valores de objetos de reemplazo, una tabla xref clásica y un trailer enlazado mediante Prev; los miembros de objetos comprimidos se materializan como objetos directos en la revisión añadida, y los bytes de los streams originales se preservan
La salida no debe ser alias de la ruta o identidad de fichero del origen; la escritura usa un fichero de staging de creación exclusiva en el directorio destino, lo vuelca y lo publica mediante rename atómico
Los fallos de presupuesto, cancelación o serialización preservan un destino existente y eliminan el fichero de staging no publicado; el origen permanece en solo lectura
El PDF de revisión anotado nativo exporta resaltados Unicode reales y apariencias visibles con permisos de anotación autenticados, reteniendo el documento cargado original y las revisiones de firmas
Bordes del formato
El perfil actual soporta el cifrado Standard AES-256 R5 y R6, diagnostica explícitamente los handlers de seguridad y filtros de stream no soportados y rechaza las generaciones retiradas de objetos libres que su escritor no puede representar
Los streams xref de bootstrap exigen valores de diccionario directos y un Length directo y acotado; las anchuras malformadas, los solapes de subsecciones, los offsets sin signo por encima de Int64, los desajustes 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 predictores soportados y longitudes de stream indirectas; los payloads de imagen 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 confianza
Aceptación
Las familias rich de fuentes con nombre añaden múltiples familias reales suministradas mediante SetRichTextFieldValueWithFamilies e ImportRichFormDataWithFamiliesToFile, con las políticas existentes de campos, seguridad y transacciones
Los campos de texto rich nativos aportan runs tipados con estilo, 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 construye 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 documento
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 coincidencias copia la revisión actual exacta, y la eliminación incremental retiene los bytes históricos