THPDFHeadlessDocument

HPDFHeadlessDocument fornece uma API de documentos de console para Linux nativo e Windows usando o parser existente de objetos do HotPDF, helpers de Direct File, decoders de fontes, interpretador de conteúdo, decoders de filters e o writer de xrefs

O loader de documentos aceita tabelas clássicas de cross-references, xref streams, seções híbridas de xref, cadeias incrementais Prev, objetos diretos e comprimidos, recursos herdados de páginas, arrays de conteúdo, Form XObjects e trees de campos AcroForm

Streams laterais híbridos têm precedência sobre a tabela acompanhante, enquanto revisões mais novas têm precedência sobre as mais antigas; membros de object-streams são decodificados e parseados sob demanda pelo parser compartilhado de objetos

Ciclo de vida e posse

Create usa THPDFHeadlessDocumentOptions.Default, enquanto o overload de opções aceita orçamentos explícitos e um token de cancelamento de posse do chamador

LoadFromFile fecha o documento anterior, abre a origem somente leitura, carrega o grafo atual de objetos e fecha o estado parcial em falha; Close libera a origem e todos os objetos carregados

LoadFromFile(FileName, Password) autentica documentos Standard AES-256 R5 ou R6 através de THPDFHeadlessAES256Security; o overload original de um argument usa senha vazia

Senhas de usuário precisam conceder extração de texto ou preenchimento de formulários antes que essas operações executem, enquanto senhas de owner burlam as restrições de permissões de usuários; senhas erradas, mismatches autenticados de Perms, operações negadas e payloads malformados de cifras têm diagnósticos distintos de documentos

Strings e streams diretos são descriptografados pelo código criptográfico compartilhado, membros comprimidos são descriptografados junto do container deles, e substituições incrementais criptografadas permanecem criptografadas sob as chaves e a política de permissões originais

Senhas usam bytes UTF-8 truncados em 127 bytes, sem normalização SASLprep; handlers não suportados, Crypt filters explícitos e políticas de MAC do PDF são diagnosticados, e não ignorados

Chaves codificadas de dicionários e nomes de recursos são decodificados antes do uso, maiúsculas permanecem significativas, e chaves decodificadas duplicadas são rejeitadas; flags de campos e MaxLen precisam caber na faixa suportada não negativa de 32 bits

Instâncias não são thread-safe; use uma instância por worker e mantenha o token de cancelamento dela vivo até a instância ser destruída

Páginas e texto

PageCount reporta o número de folhas da page tree; ExtractPageText(PageIndex) aceita um índice com base zero e retorna texto Unicode montado pelo interpretador compartilhado de glyphs

ExtractPageTextBounded aplica limites temporários de glyphs e streams antes da preparação de texto e restaura todas as opções originais de recursos após sucesso, falha ou cancelamento

GetObjectAccess expõe acesso emprestado read-only de catalog, information e objetos, com alocação delimitada de índices, para comparação nativa estrutural e completa

A decodificação de texto segue encodings de fontes, diferenças de encodings, CMaps ToUnicode embutidos, widths explícitos e o provider de métricas de fontes padrão; Form XObjects aninhados aplicam as matrizes deles e usam os dicionários próprios ou herdados de recursos

O fallback de fontes padrão do Linux exige Fontconfig e fontes TrueType instaladas; fontes complexas de documentos precisam fornecer uma estratégia suportada de decodificação, e recursos de fontes ausentes produzem um diagnóstico

AppendPageText adiciona texto Unicode visível ou invisível ajustado, retendo o conteúdo original das páginas e as políticas criptografadas de segurança

AppendImportedPages clona grafos selecionados de recursos de páginas, geometria herdada e aparências normais visíveis, preservando revisões existentes do destino e a política autenticada de criptografia

Valores de texto AcroForm

FormFieldCount, GetFormField(FieldIndex) e FindFormField(Name) enumeram campos terminais usando nomes totalmente qualificados e tipos, flags, comprimentos máximos e valores herdados de campos; índices têm base zero, e um nome ausente retorna -1

SetTextFieldValue(FieldIndex, Text) aceita campos Tx graváveis, grava uma PDF string UTF-16BE e define NeedAppearances=true no dicionário AcroForm

Este método somente de valor conta com a regeneração pelo viewer; viewers que não regeneram aparências podem continuar exibindo uma aparência antiga ou um widget vazio

SetTextFieldValueWithAppearance gera aparências Unicode explícitas para todo widget existente usando uma fonte TrueType fornecida pelo chamador, métricas reais de glyphs, encoding Identity-H, ToUnicode e embutimento completo de FontFile2

O perfil de aparências suporta texto de linha única e multilinha, wrapping, células comb, rotações em quartos de volta, tamanho fixo ou auto-fit, alinhamento e shaping complexo nativo opcional HarfBuzz/FriBidi

SetChoiceFieldValuesWithAppearance lida com list boxes de seleção múltipla, opções herdadas, arrays ordenados de export e toda linha selecionada visível; o helper de valor único também suporta rótulos export/display de combos

GetChoiceFieldValues lê o array completo selecionado de exports; SetButtonFieldValueWithAppearance e SetPushButtonAppearance geram estados e captions reais de botões

Novos objetos e streams de aparências são delimitados antes das mudanças de campos e permanecem criptografados sob a política original de segurança AES quando salvos; Cairo nativo do Linux e readers independentes consomem os mesmos objetos gerados

Métodos de campos de texto aplicam flags read-only, MaxLen em unidades de código UTF-16 e o tipo do campo; campos choice e button usam seus métodos de aparências separados, enquanto formulários XFA ficam fora do perfil AcroForm deste carregador de documentos

Documentos assinados usam políticas autenticadas DocMDP e FieldMDP: atualizações de formulários permitidas preservam revisões assinadas existentes, enquanto campos bloqueados, restrições P1 e tentativas de sobrescrever campos de assinatura assinados são rejeitadas

Evidências validadas de DSS/VRI adicionam dados autenticados de certificados e revogação a uma revisão incremental sem alterar assinaturas existentes de ByteRange

Verificação de assinaturas

SignatureCount enumera campos assinados de assinaturas AcroForm, e VerifySignature(SignatureIndex, Options) valida assinaturas com base zero usando o parser compartilhado e o provider de CMS OpenSSL 3 em streaming

O perfil PDF aceita adbe.pkcs7.detached e o ETSI.CAdES.detached reconhecido automaticamente, com Contents hexadecimal ou literal padrão; CAdES sempre autentica o binding ESS signing-certificate, enquanto configurações explícitas de CA avaliam a confiança separadamente

DocTimeStamp com ETSI.RFC3161 autentica automaticamente o TSTInfo encapsulado genuíno, ESS, propósito do TSA e nome do signer, e o imprint exato do PDF; roots e CRLs configurados de timestamps avaliam separadamente a confiança no TSA

A verificação valida o gap não assinado exato, incluindo os delimitadores dele, e vincula os bytes decodificados dele ao dicionário atual de assinaturas antes da verificação criptográfica

O resultado distingue integridade, confiança explicitamente avaliada de CAs e bytes não assinados após a revisão autenticada; perfis não suportados de assinaturas PDF produzem um diagnóstico tipado

Veja HPDFVerifyHeadlessCMS para os requisitos de runtime e THPDFHeadlessCMSOptions para orçamentos e configurações de confiança

Assinaturas incrementais de aprovação

SignToFile assina um campo Sig existente gravável e não assinado e publica um PDF independentemente atualizado incrementalmente usando um certificado PEM fornecido pelo chamador e uma chave privada PEM não criptografada

AddSignatureField cria um widget de página e os links AcroForm dele, incluindo um AcroForm novo num PDF importado simples; SetSignatureFieldAppearance gera a caption visível dele, e SignPFXToFile carrega uma identidade de certificado/chave PKCS12 com a cadeia dela

CertificationPermission cria a primeira assinatura de certificação DocMDP; P2 e P3 permitem assinaturas de aprovação subsequentes em campos existentes, enquanto P1 rejeita assinaturas adicionais

Os bytes originais da origem e o grafo carregado de objetos permanecem inalterados; assinaturas de aprovação posteriores preservam os bytes de assinaturas anteriores e as fronteiras autenticadas de revisões delas

Criptografia Standard AES-256 R5 e R6, senhas, IDs e permissões permanecem em vigor, incluindo origens de object-streams criptografados; a string Contents de assinaturas segue a exceção de criptografia do PDF

Valores existentes de assinaturas, campos read-only, políticas de documentos certificados, permissões negadas de form-fill, tokens de cancelamento divergentes e orçamentos esgotados de saída são rejeitados sem publicar uma saída

Document timestamps

TimestampToFile cria um document timestamp RFC 3161 genuíno num campo de assinaturas existente não assinado, sem chave de assinatura da aplicação, usando um transporte TSA de posse do chamador e confiança explícita no TSA

O writer preserva as revisões originais e a segurança AES, declara a extensão ESIC para entrada anterior ao PDF 2.0, e publica atomicamente somente depois que as checagens de nonce, imprint, assinatura, certificado, revogação configurada e seeds passam

Mudanças necessárias autenticadas de document timestamps são permitidas sob DocMDP e FieldMDP; edições comuns de formulários e assinaturas de aprovação retêm as restrições originais delas

Interchange de formulários FDF e XFDF

ExportAnnotationsFDF exporta grafos de objetos de anotações delimitados e seus recursos de aparências compartilhados; SaveAnnotationsFDFToFile prepara substituições nomeadas e anexa numa revisão incremental independente e atômica de PDF

O perfil binário de anotações FDF preserva a criptografia e a política de assinatura do documento autenticado, referências contextuais de páginas GoTo locais e publicação exata inalterada; ele deixa o documento carregado inalterado após salvar

SaveAnnotationsXFDFToFile anexa anotações mapeadas delimitadas a uma revisão incremental independente; HPDFExportHeadlessAnnotationsXFDF retorna os bytes XFDF delas

ExportFormData retorna dados delimitados de campos Unicode, incluindo arrays reais de choices e estados de export de checkboxes e radios

ImportFormDataToFile regenera aparências genuínas num grafo privado autenticado de revisões e publica atomicamente um PDF incremental, preservando o estado da origem carregada

ImportRichFormDataToFile importa o perfil delimitado XHTML de FDF RV ou XFDF value-richtext com programas reais de fontes regular, bold, italic e bold-italic

SaveRichTextFieldUpdatesToFile aplica campos escalares e runs rich tipados originais numa única revisão atômica independente, preservando programas reais de fontes e a precisão numérica PDF; campos protegidos inalterados exigem aparências decodificadas e recursos resolvidos correspondentes para cada widget

Criptografia existente, flags read-only, DocMDP e FieldMDP autenticados, assinaturas originais, cancelamento e orçamentos de recursos permanecem aplicados; veja Form data nativo de FDF e XFDF para a sintaxe suportada e as fronteiras escalares de interchange

Acesso emprestado de rendering

GetRenderAccess(PageIndex) fornece o dicionário existente da página, recursos herdados, resolver de fontes, resolução de objetos, checagem de permissões, token de cancelamento e callbacks delimitados de streams decodificados através de THPDFHeadlessRenderAccess

Esta é uma view emprestada serial e somente leitura; o documento precisa permanecer carregado e inalterado até o renderer terminar, e os chamadores não devem mutar o grafo de objetos exposto por ele

O callback RequireOutputPath da view checa uma saída prospectiva contra o path canônico e a identidade física de arquivo da origem, sem criar nem modificar arquivo

Saída independente

ExtractPageGlyphs retorna glyphs posicionados pelo walker delimitado de conteúdo aninhado; AnalyzePageSemanticText fornece texto semântico e geometria da origem para a comparação nativa de contratos

SaveToFile(FileName) copia os bytes originais e anexa valores de substituição de objetos, uma tabela clássica de xref e um trailer vinculado através de Prev; membros comprimidos de objetos são materializados como objetos diretos na revisão anexada, e os bytes originais dos streams são preservados

A saída não pode ser alias do path nem da identidade de arquivo da origem; a gravação usa um arquivo de staging criado exclusivamente no diretório de destino, faz flush dele, e o publica por rename atômico

Falhas de orçamento, cancelamento ou serialização preservam um destino existente e apagam o arquivo de staging não publicado; a origem permanece somente leitura

O PDF de revisão anotado nativo exporta highlights Unicode reais e aparências visíveis com permissões autenticadas de anotações, retendo o documento original carregado e as revisões de assinaturas

Fronteiras de formatos

O perfil atual suporta criptografia Standard AES-256 R5 e R6, diagnostica explicitamente security handlers e stream filters não suportados, e rejeita gerações aposentadas de free objects que não podem ser representadas pelo writer dele

Bootstrap xref streams exigem valores diretos de dicionários e um Length direto e delimitado; widths malformados, sobreposição de subseções, offsets sem sinal acima de Int64, mismatches de membros comprimidos, ciclos de referências e limites configurados produzem diagnósticos tipados

O conteúdo decodificado suporta filters Flate, ASCIIHex, ASCII85 e LZW com predictors suportados e comprimentos indiretos de streams; payloads de imagens não são decodificados para extração de texto

Os workflows nativos de assinatura cobrem campos de assinaturas, aparências visíveis e certificação; as políticas autenticadas de formulários assinados e as APIs de timestamps e validação de longo prazo retêm as opções explícitas delas de integridade e confiança

Aceitação

Famílias de fontes rich nomeadas adicionam múltiplas famílias realmente fornecidas através de SetRichTextFieldValueWithFamilies e ImportRichFormDataWithFamiliesToFile, com as políticas existentes de campos, segurança e transações

Campos nativos de rich text fornecem runs tipados estilizados, aparências reais de fontes de estilos embutidas, valores sincronizados V e RV, saída incremental criptografada e edições transacionais delimitadas; GetRichTextFieldValue lê XHTML armazenado ou herdado

Tests/Linux/Run-HeadlessDocumentTests.sh compila um executável ELF nativo com as variáveis de desktop limpas e checa dependências de bibliotecas GUI; Run-HeadlessDocumentTests-Windows.cmd Win32 e Win64 exercitam a mesma API compartilhada de documentos

Veja THPDFHeadlessFormField, EHPDFHeadlessDocumentError e THPDFHeadlessDiagnosticCode para os valores retornados e os diagnósticos tipados

Remoção de anotações

Remova anotações de páginas pela identidade exata de página e nome Unicode através de SaveAnnotationRemovalsToFile, com cascatas de popups e replies, preparação delimitada e saída separada atômica

O documento carregado permanece inalterado; uma seleção inalterada copia a revisão atual exata, e a remoção incremental retém bytes históricos