THPDFHeadlessDocument
HPDFHeadlessDocument fornece uma API de documentos de consola para Linux e Windows nativos usando o parser existente de objetos do HotPDF, helpers de Direct File, descodificadores de tipos de letra, intérprete de conteúdo, descodificadores de filtros e escritor de xrefs
O loader de documentos aceita tabelas clássicas de referências cruzadas, xref streams, secções hybrid de xrefs, cadeias incrementais de Prev, objetos diretos e comprimidos, recursos herdados de páginas, arrays de conteúdo, Form XObjects e árvores de campos AcroForm
Streams laterais hybrid têm precedência sobre a tabela acompanhante, enquanto revisões mais recentes têm precedência sobre as mais antigas; os membros de object streams são descodificados e analisados preguiçosamente através do parser partilhado de objetos
Ciclo de vida e propriedade
Create usa THPDFHeadlessDocumentOptions.Default, enquanto a sobrecarga de opções aceita orçamentos explícitos e um token de cancelamento próprio de quem chama
LoadFromFile fecha o documento anterior, abre a fonte só de leitura, carrega o grafo atual de objetos e fecha o estado parcial em caso de falha; Close liberta a fonte e todos os objetos carregados
LoadFromFile(FileName, Password) autentica documentos Standard AES-256 R5 ou R6 através de THPDFHeadlessAES256Security; a sobrecarga original de um argumento usa uma palavra-passe vazia
Palavras-passe de utilizadores têm de conceder extração de texto ou preenchimento de formulários antes de essas operações executarem, enquanto palavras-passe de proprietários contornam as restrições de permissões de utilizadores; palavras-passe erradas, desacordos autenticados de Perms, operações negadas e payloads de cifras malformados têm diagnósticos distintos de documentos
Strings e streams diretas são desencriptadas através do código criptográfico partilhado, membros comprimidos são desencriptados apenas com o contentor deles, e substituições incrementais encriptadas permanecem encriptadas sob as chaves e a política de permissões originais
As palavras-passe usam bytes UTF-8 truncados a 127 bytes sem normalização SASLprep; handlers não suportados, crypt filters explícitos e políticas de PDF MAC são diagnosticados em vez de ignorados
Chaves codificadas de dicionários e nomes de recursos são descodificadas antes do uso, as maiúsculas e minúsculas permanecem significativas, e chaves descodificadas duplicadas são rejeitadas; flags de campos e MaxLen têm de caber no intervalo suportado não negativo de 32 bits
As 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 árvore de páginas; ExtractPageText(PageIndex) aceita um índice com base zero e devolve texto Unicode montado a partir do intérprete partilhado de glyphs
ExtractPageTextBounded aplica limites temporários de glyphs e de 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 só de leitura a catalog, informação e objetos com alocação delimitada de índices para a comparação nativa estrutural e completa
A descodificação de texto segue encodings de tipos de letra, diferenças de encodings, CMaps ToUnicode incorporadas, larguras explícitas e o fornecedor de métricas de tipos de letra standard; Form XObjects aninhados aplicam as matrizes deles e usam os dicionários de recursos próprios ou herdados deles
O fallback de Linux de tipos de letra standard exige Fontconfig e tipos de letra TrueType instalados; tipos de letra complexos de documentos têm de fornecer uma estratégia suportada de descodificação, e recursos de tipos de letra em falta produzem um diagnóstico
AppendPageText acrescenta texto Unicode visível ou invisível ajustado mantendo o conteúdo original das páginas e as políticas encriptadas 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 encriptação
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; os índices têm base zero, e um nome em falta devolve -1
SetTextFieldValue(FieldIndex, Text) aceita campos Tx graváveis, escreve uma string PDF UTF-16BE e define NeedAppearances=true no dicionário AcroForm
Este método apenas de valores depende da regeneração pelos leitores; leitores que não regeneram aparências podem continuar a apresentar uma aparência antiga ou um widget vazio
SetTextFieldValueWithAppearance gera aparências Unicode explícitas para todos os widgets existentes usando um tipo de letra TrueType fornecido por quem chama, métricas reais de glyphs, encoding Identity-H, ToUnicode e embedding completo de FontFile2
O perfil de aparências suporta texto de linha única e multilinha, wrap, células comb, rotações de quarto de volta, tamanho fixo ou auto-fit, alinhamento e shaping complexo nativo opcional HarfBuzz/FriBidi
SetChoiceFieldValuesWithAppearance trata list boxes de seleção múltipla, opções herdadas, arrays ordenados de exportações e todas as linhas selecionadas visíveis; o helper de valor único também suporta etiquetas de exportação/apresentação de combos
GetChoiceFieldValues lê o array completo de exportações selecionadas; SetButtonFieldValueWithAppearance e SetPushButtonAppearance geram estados e captions reais de botões
Objetos e streams novos de aparências são delimitados antes de alterações de campos e permanecem encriptados sob a política original de segurança AES quando guardados; Cairo nativo de Linux e leitores independentes consomem os mesmos objetos gerados
Os métodos de campos de texto impõem flags só de leitura, MaxLen em unidades de código UTF-16 e o tipo do campo; campos choice e button usam os 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
A evidência validada de DSS/VRI acrescenta dados autenticados de certificados e de revogação a uma revisão incremental sem alterar assinaturas ByteRange existentes
Verificação de assinaturas
SignatureCount enumera campos assinados de assinaturas AcroForm e VerifySignature(SignatureIndex, Options) valida assinaturas com base zero usando o parser partilhado e o fornecedor streaming OpenSSL 3 CMS
O perfil PDF aceita adbe.pkcs7.detached e ETSI.CAdES.detached automaticamente reconhecido com Contents hexadecimais ou literais standard; CAdES autentica sempre o binding ESS signing-certificate, enquanto definições explícitas de CAs avaliam a confiança separadamente
DocTimeStamp com ETSI.RFC3161 autentica automaticamente TSTInfo genuíno encapsulado, ESS, propósito TSA e nome do signer, e o imprint PDF exato; raízes e CRLs configuradas de timestamps avaliam separadamente a confiança TSA
A verificação valida o intervalo não assinado exato incluindo os delimitadores dele e vincula os bytes descodificados 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 PDF de assinaturas não suportados produzem um diagnóstico tipado
Veja HPDFVerifyHeadlessCMS para requisitos de runtime e THPDFHeadlessCMSOptions para orçamentos e definiçõ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 incrementalmente atualizado independente usando um certificado PEM e uma chave privada PEM não encriptada fornecidos por quem chama
AddSignatureField cria um widget de páginas e as ligações 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 fonte e o grafo carregado de objetos permanecem inalterados; assinaturas de aprovação posteriores preservam bytes de assinaturas anteriores e as fronteiras autenticadas de revisões delas
Encriptação Standard AES-256 R5 e R6, palavras-passe, IDs e permissões permanecem em vigor, incluindo fontes de object streams encriptadas; a string Contents da assinatura segue a isenção PDF de encriptação
Valores existentes de assinaturas, campos só de leitura, políticas de documentos certificados, permissões negadas de preenchimento de formulários, tokens de cancelamento divergentes e orçamentos de saída esgotados são rejeitados sem publicar saída nenhuma
Timestamps de documentos
TimestampToFile cria um timestamp de documentos RFC 3161 genuínum num campo de assinatura existente não assinado sem uma chave de assinatura de aplicações, usando um transport TSA próprio de quem chama e confiança explícita TSA
O escritor preserva revisões originais e segurança AES, declara a extensão ESIC para entradas anteriores ao PDF 2.0 e publica atomicamente apenas depois das verificações de nonce, imprint, assinatura, certificados, revogação configurada e seeds passarem
Alterações necessárias autenticadas de timestamps de documentos são permitidas sob DocMDP e FieldMDP; edições ordinárias de formulários e assinaturas de aprovação mantêm as restrições originais delas
Intercâmbio de formulários FDF e XFDF
ExportAnnotationsFDF exporta grafos de objetos de anotações delimitados e os seus recursos de aparências partilhados; SaveAnnotationsFDFToFile prepara substituições nomeadas e acrescenta numa revisão incremental independente e atómica de PDF
O perfil binário de anotações FDF preserva a cifragem e a política de assinaturas do documento autenticado, referências contextuais de páginas GoTo locais e publicação exata inalterada; deixa o documento carregado inalterado após guardar
SaveAnnotationsXFDFToFile acrescenta anotações mapeadas delimitadas a uma revisão incremental independente; HPDFExportHeadlessAnnotationsXFDF devolve os bytes XFDF delas
ExportFormData devolve dados delimitados de campos Unicode, incluindo arrays reais de escolhas e estados de exportação de checkboxes e radios
ImportFormDataToFile regenera aparências genuínas sobre um grafo privado autenticado de revisões e publica atomicamente um PDF incremental mantendo o estado da fonte carregada
ImportRichFormDataToFile importa o perfil XHTML delimitado de FDF RV ou XFDF value-richtext com programas reais de tipos de letra regular, bold, italic e bold-italic
SaveRichTextFieldUpdatesToFile aplica campos escalares e runs rich tipados originais numa revisão atómica independente única, preservando programas reais de tipos de letra e precisão numérica PDF; campos protegidos inalterados exigem aparências descodificadas correspondentes e recursos resolvidos para todos os widgets
Encriptação existente, flags só de leitura, DocMDP e FieldMDP autenticados, assinaturas originais, cancelamento e orçamentos de recursos permanecem impostos; veja os dados nativos de formulários FDF e XFDF para a sintaxe suportada e as fronteiras de intercâmbio escalar
Acesso emprestado de renderização
GetRenderAccess(PageIndex) fornece o dicionário existente de páginas, recursos herdados, resolver de tipos de letra, resolução de objetos, verificação de permissões, token de cancelamento e callbacks delimitados de streams descodificadas através de THPDFHeadlessRenderAccess
Esta é uma vista emprestada só de leitura e em série; o documento tem de permanecer carregado e inalterado até o renderer terminar, e quem chama não deve mutar o grafo de objetos exposto por ele
O callback RequireOutputPath da vista verifica uma saída potencial contra o caminho canónico da fonte e a identidade física do ficheiro dela sem criar nem alterar um ficheiro
Saída independente
ExtractPageGlyphs devolve glyphs posicionados através do percorredor delimitado aninhado de conteúdo; AnalyzePageSemanticText fornece texto semântico e geometria fonte para a comparação nativa de contratos
SaveToFile(FileName) copia os bytes originais e acrescenta valores de substituição de objetos, uma tabela clássica de xrefs e um trailer ligado através de Prev; membros comprimidos de objetos são materializados como objetos diretos na revisão acrescentada, e os bytes originais das streams são preservados
A saída não pode ser alias do caminho nem da identidade do ficheiro fonte; a escrita usa um ficheiro de staging criado exclusivamente no diretório de destino, faz flush dele e publica-o por rename atómico
Falhas de orçamento, cancelamento ou serialização preservam um destino existente e apagam o ficheiro de staging não publicado; a fonte permanece só de leitura
O PDF de revisão anotado nativo exporta destaques Unicode reais e aparências visíveis com permissões autenticadas de anotações, mantendo o documento carregado original e as revisões de assinaturas
Fronteiras de formatos
O perfil atual suporta encriptação Standard AES-256 R5 e R6, diagnostica explicitamente security handlers e filtros de streams não suportados e rejeita gerações aposentadas de objetos livres que o escritor dele não consegue representar
Xref streams de bootstrap exigem valores diretos de dicionários e um Length direto e delimitado; larguras malformadas, sobreposições de subsecções, offsets sem sinal acima de Int64, desacordos de membros comprimidos, ciclos de referências e limites configurados produzem diagnósticos tipados
O conteúdo descodificado suporta filtros Flate, ASCIIHex, ASCII85 e LZW com preditores suportados e comprimentos indiretos de streams; payloads de imagens não são descodificados para extração de texto
Os workflows nativos de assinatura cobrem campos de assinaturas, aparências visíveis e certificação; políticas autenticadas de formulários assinados, APIs de timestamps e de validação de longo prazo mantêm as opções explícitas delas de integridade e de confiança
Aceitação
Famílias rich nomeadas de tipos de letra acrescentam 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 com estilo, aparências reais de tipos de letra de estilos incorporados, valores V e RV sincronizados, saída incremental encriptada e edições transacionais delimitadas; GetRichTextFieldValue lê XHTML guardado ou herdado
Tests/Linux/Run-HeadlessDocumentTests.sh compila um executável ELF nativo com variáveis de desktop limpas e verifica dependências de bibliotecas GUI; Run-HeadlessDocumentTests-Windows.cmd Win32 e Win64 exercitam a mesma API partilhada de documentos
Veja THPDFHeadlessFormField, EHPDFHeadlessDocumentError e THPDFHeadlessDiagnosticCode para valores devolvidos e 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 respostas, 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