THotPDF Preflight Report Methods

Sintaxe

type
  THPDFPreflightFormat = (pfText, pfJSON, pfHTML, pfCSV);

function CreatePreflightReport(const SourceFile: TFileName): AnsiString;
function CreatePreflightReport(
  const SourceFile: TFileName;
  const Password  : AnsiString): AnsiString;
function CreatePreflightReport(
  const SourceFile: TFileName;
  const Password  : AnsiString;
  const Format    : THPDFPreflightFormat): AnsiString;
procedure SavePreflightReport(
  const SourceFile: TFileName;
  const ReportFile: TFileName);
procedure SavePreflightReport(
  const SourceFile: TFileName;
  const ReportFile: TFileName;
  const Password  : AnsiString);
procedure SavePreflightReport(
  const SourceFile: TFileName;
  const ReportFile: TFileName;
  const Password  : AnsiString;
  const Format    : THPDFPreflightFormat);
function ValidatePDFVT(
  const SourceFile: TFileName;
  out Report      : AnsiString): Boolean;
function ValidatePDFVT(
  const SourceFile: TFileName;
  const Password  : AnsiString;
  out Report      : AnsiString): Boolean;
procedure EmbedPreflightReportInPDF(
  const SourceFile: TFileName;
  const TargetFile: TFileName);
procedure EmbedPreflightReportInPDF(
  const SourceFile: TFileName;
  const TargetFile: TFileName;
  const Password  : AnsiString);
function LoadAndValidatePreflightReport(
  const EmbeddedFile  : TFileName;
  out OriginalReport: AnsiString;
  out CurrentReport : AnsiString): Boolean;
function LoadAndValidatePreflightReport(
  const EmbeddedFile  : TFileName;
  const Password      : AnsiString;
  out OriginalReport: AnsiString;
  out CurrentReport : AnsiString): Boolean;
function ComparePreflightReports(
  const ReportA: AnsiString;
  const ReportB: AnsiString): AnsiString;
function RepairPDFFromPreflightReport(
  const SourceFile: TFileName;
  const TargetFile: TFileName;
  out RepairsApplied: AnsiString): Boolean;
function RepairPDFFromPreflightReport(
  const SourceFile: TFileName;
  const TargetFile: TFileName;
  const Password  : AnsiString;
  out RepairsApplied: AnsiString): Boolean;
function AggregatePreflightReports(
  const Reports: array of AnsiString): AnsiString;
type
  THPDFPreflightProfile = record
    DisableChecks  : AnsiString;
    DisableWarnings: AnsiString;
    DisableHints   : Boolean;
  end;
function LoadPreflightProfile(
  const ProfileFile: TFileName): THPDFPreflightProfile;
function ApplyPreflightProfile(
  const Report : AnsiString;
  const Profile: THPDFPreflightProfile): AnsiString;
function ValidatePreflightProfile(
  const Profile: THPDFPreflightProfile;
  out UnknownNames: AnsiString): Boolean;
function GetBuiltInPreflightProfile(
  const Name: AnsiString): THPDFPreflightProfile;
procedure SavePreflightProfile(
  const Profile    : THPDFPreflightProfile;
  const ProfileFile: TFileName);
function CreatePreflightReportWithProfile(
  const SourceFile : TFileName;
  const Password   : AnsiString;
  const ProfileFile: TFileName;
  const Format     : THPDFPreflightFormat): AnsiString;
function MergePreflightProfiles(
  const A, B: THPDFPreflightProfile): THPDFPreflightProfile;
function DiffPreflightProfiles(
  const A, B  : THPDFPreflightProfile;
  out OnlyInA: AnsiString;
  out OnlyInB: AnsiString): Boolean;
procedure EmbedPreflightReportAsXMP(
  const SourceFile: TFileName;
  const TargetFile: TFileName);
procedure EmbedPreflightReportAsXMP(
  const SourceFile: TFileName;
  const TargetFile: TFileName;
  const Password  : AnsiString);
function ConvertPreflightReportToVeraPDFStyle(
  const Report: AnsiString): AnsiString;

Descrição

CreatePreflightReport lê um PDF de entrada e retorna um relatório de texto com verificações estruturais leves. As sobrecargas com senha usam o caminho de carregamento existente com suporte a senha para PDFs criptografados compatíveis. SavePreflightReport grava o mesmo relatório em um arquivo de texto de destino

ValidatePDFVT executa uma passagem focada de validação PDF/VT e retorna True somente quando os marcadores e estruturas necessários estão presentes. O relatório de texto retornado verifica a declaração XMP pdfvtid:GTS_PDFVTVersion, namespace de metadados PDF/VT, correspondência entre data de modificação PDF/VT e xmp:ModifyDate, marcador base PDF/X, ausência de criptografia, output intent PDF/X, Catalog DPartRoot, DPartRootNode, NodeNameList, presença de partes do documento, contagem de páginas carregáveis e cobertura DPart em nível de página. Propriedades de data PDF/VT e XMP podem ser gravadas como texto de elemento ou como atributos RDF em um elemento rdf:Description

O relatório verifica cabeçalho PDF, marcador EOF, se o marcador final %%EOF fica perto do fim do arquivo, o último offset startxref, se esse offset aponta para uma tabela xref ou xref stream, contagens de marcadores %%EOF e startxref, equilíbrio de marcadores de revisão e ordenação final, marcador trailer ou XRef stream, contagem de páginas carregáveis, estado de criptografia, catálogo, árvore de páginas, marcador de objeto de página, MediaBox, referência de dicionário de informações, referência raiz, contagem de objetos indiretos, contagem de definições de objetos indiretos, maior número de objeto, contagem de números de objeto duplicados, unicidade de números de objeto, contagem de objetos de catálogo, contagem de objetos da árvore de páginas, contagem de objetos de página, contagem declarada da árvore de páginas, consistência entre contagem da árvore de páginas e páginas carregáveis, consistência entre objetos de página e páginas carregáveis, equilíbrio stream e endstream, cobertura de entrada stream /Length, contagem de tabelas xref, contagem de subseções xref, contagens de entradas de tabela xref, contagens de entradas xref livres e em uso, contagem de linhas xref malformadas, validade de linhas xref, cobertura xref contra números de objeto, contagem de xref stream, contagem de object stream, contagem de trailer, trailer /Size, se trailer /Size cobre o maior número de objeto, referências indiretas trailer /Root e /Info, se esses objetos referenciados estão definidos, se trailer /Root aponta para um objeto de catálogo, contagem e estrutura de par da matriz trailer /ID, presença de trailer /Root, /Info, /ID e /Encrypt, contagem estimada de atualização incremental, status de linearização, caixas de página carregadas, contagem de campos de formulário, contagem de dicionários de recursos, contagem de recursos de fonte, contagem de programas de fonte incorporados (/FontFile, /FontFile2, /FontFile3), contagem de XObject de imagem, contagem de XObject de formulário, contagem de recursos ColorSpace, contagem de anotações e subcontagens de widget/link, contagens de uso de cadeias de filtro para FlateDecode, DCTDecode, CCITTFaxDecode, JBIG2Decode, LZWDecode, ASCIIHexDecode, ASCII85Decode, RunLengthDecode e JPXDecode, cobertura de incorporação de fontes, consistência de contagem de anotações, dicas de conformidade PDF/A / PDF/X / PDF/UA / Tagged PDF / transparência, flags de recurso selecionadas, avisos de JavaScript ou ações (cobrindo todo o conjunto de ações do PDF 1.7 sec 12.6.4: GoTo*, Thread, URI, Sound, Movie, Hide, Named, SubmitForm, ResetForm, ImportData, SetOCGState, Rendition, Trans e GoTo3DView, além de verificações legadas JavaScript / Launch / OpenAction / AdditionalActions / EmbeddedFile / RichMedia e avisos de exclusão mútua de PDF/A), totais de avisos e um resumo geral de aprovado/falhou. Estes helpers servem como verificações rápidas em processo antes de encaminhar arquivos a validadores externos de padrões; eles não substituem um mecanismo completo de validação PDF/A, PDF/X, PDF/UA ou ISO 32000 preflight

The Format overload accepts pfText (default plain-text path, byte-stable with the legacy overloads), pfJSON (CI-friendly JSON document), or pfHTML (dashboard-ready, self-contained HTML report with inline CSS and severity-coloured rows). The JSON output groups entries into input, size, pdfVersion, and xrefStyle top-level fields plus checks, info, hints, and warnings arrays and a summary object carrying failed, warnings, and result values. The built-in JSON encoder escapes ", \, and control bytes; UTF-8 byte sequences pass through unchanged.

Cada entrada de verificações, dicas e avisos carrega um campo spec opcional que nomeia a cláusula ISO visada pelo diagnóstico (por exemplo, ISO 32000-1 sec 7.5.5 para verificações relacionadas a trailer, ISO 19005-1 sec 6.6.2 para o aviso de exclusão mútua de PDF/A com JavaScript). O mapeamento cobre toda verificação, dica e aviso emitidos pelo relatório até a v2.122.0. Um JSON Schema formal (draft 2020-12) que descreve a estrutura de saída pfJSON é publicado em Docs/preflight-schema.json para que consumidores posteriores validem a saída antes de analisá-la

EmbedPreflightReportInPDF grava uma cópia do PDF de origem em TargetFile com o relatório preflight textual legado anexado após o último %%EOF como linhas de comentário em estilo PDF (cada linha prefixada com % ). Leitores PDF ignoram os bytes anexados porque eles ficam fora do grafo de objetos, mas fluxos de arquivamento, editores de texto e ferramentas tipo grep ainda conseguem expor o relatório incorporado para auditoria posterior. O grafo de objetos original, a tabela de referência cruzada e o trailer não são modificados

LoadAndValidatePreflightReport extracts the report that EmbedPreflightReportInPDF previously appended, re-runs the current preflight algorithm against the source bytes preceding the embedded comment block, and compares the InputFingerprint values. The function returns True when both fingerprints match, indicating the embedded report still describes the file as it exists on disk When validation fails, callers can inspect OriginalReport and CurrentReport to diff what changed.

ComparePreflightReports emits a unified-diff-like body for two reports. Shared lines appear with a two-space prefix, lines unique to ReportA are prefixed with - , and lines unique to ReportB are prefixed with + . The algorithm is tuned for the well-formed key/value output produced by CreatePreflightReport where line order is deterministic; it is not a general-purpose LCS implementation but produces compact, readable diffs for the typical case of mostly-unchanged reports.

RepairPDFFromPreflightReport applies a conservative subset of byte-level repairs to a damaged PDF: it drops trailing bytes that follow the final %%EOF marker, and appends a missing %%EOF when one is not present anywhere. The function returns True when at least one repair was applied; RepairsApplied lists the repairs as one line per change. Object-graph repairs (rebuilding xref tables, patching stream lengths, fixing trailer dictionaries) are intentionally out of scope because such fixes can make a partially-recoverable file less recoverable; use a dedicated PDF recovery tool for deeper damage.

AggregatePreflightReports recebe uma matriz de relatórios por arquivo e produz um único resumo de lote. Cada entrada da matriz é analisada por seus campos Input, Size e Summary; o agregado emite uma linha por arquivo mais totais de relatórios aprovados, falhos e com aviso, bytes totais analisados e contagens gerais de resultado. Útil para pipelines CI e loops de shell que processam um diretório de PDFs e querem um resumo único e conciso no final

LoadPreflightProfile and ApplyPreflightProfile let callers tailor the report output without re-running the analysis. The profile file uses an INI-style format with three optional sections: [disable-checks] lists check names to suppress; [disable-warnings] lists warning names to suppress; and [options] accepts hints=false to suppress every Hint line. After filtering, the Summary line is recomputed so the suppressed entries no longer contribute to the Failed and Warnings totals; the rest of the report passes through unchanged.

ValidatePreflightProfile percorre as listas DisableChecks e DisableWarnings de um perfil carregado e relata qualquer nome não reconhecido pela implementação preflight atual. Útil para detectar arquivos de perfil criados para uma versão mais nova ou mais antiga do HotPDF que, de outro modo, não desabilitariam nada silenciosamente porque os nomes não correspondem a nenhuma verificação ou aviso emitido

GetBuiltInPreflightProfile returns ready-to-use profile records for common workflows. Recognised names (case-insensitive): default / '' returns an empty profile; compact disables every Hint line for shorter reports; silent-actions disables every PDF 1.7 sec 12.6.4 action warning plus EmbeddedFile and RichMedia, intended for workflows that intentionally embed multimedia or interactive actions and do not want the preflight report to flag them. Unknown names also return an empty profile.

SavePreflightProfile writes a THPDFPreflightProfile record back to an INI file in the same format that LoadPreflightProfile consumes The two functions are exact inverses for well-formed profiles, so callers can build a 'load preset, tweak, save' workflow: P := GetBuiltInPreflightProfile('compact'), edit P.DisableChecks, then SavePreflightProfile(P, 'tuned.ini') for later reuse.

CreatePreflightReportWithProfile é um wrapper de conveniência em uma chamada que compõe CreatePreflightReport, LoadPreflightProfile, ApplyPreflightProfile e os conversores de formato existentes, para que um chamador que já tem PDF de origem, senha opcional, arquivo de perfil e formato de destino possa emitir uma única chamada em vez de encadear quatro. Passar ProfileFile vazio pula a etapa do perfil

MergePreflightProfiles retorna a união deduplicada de dois perfis: DisableChecks e DisableWarnings coletam nomes das duas entradas, e DisableHints é o OR lógico. Útil para colocar um preset sobre ajustes específicos do projeto

DiffPreflightProfiles reports the structural difference between two profiles. Returns True when they are equivalent; otherwise False with OnlyInA and OnlyInB filled with newline-separated lines of the form check:<name>, warn:<name>, or option:hints=false describing which entries are exclusive to each side.

EmbedPreflightReportAsXMP is an archival-friendly variant of EmbedPreflightReportInPDF: it writes a copy of the source PDF with the preflight report appended as a PDF-style comment block whose payload is XMP / RDF (xmlns:hotpdf="http://www.loslab.com/hotpdf/preflight/") Each report line becomes a hotpdf:<name> element with severity carried as an attribute on check rows XMP-aware tools that scan a file for xpacket markers can surface the embedded report; PDF readers continue to ignore the appended bytes because they fall outside the object graph. This is intentionally not a spec-compliant XMP integration: the XMP payload is not referenced from the catalog /Metadata entry, so XMP readers that only follow the catalog reference will not see it.

ConvertPreflightReportToVeraPDFStyle molda um relatório preflight do HotPDF em um documento JSON que segue o contorno geral da saída de validação do veraPDF, com um campo profile de nível superior, uma matriz jobs contendo itemDetails / taskResult / validationResult e uma matriz ruleViolations em validationResult.details. O formato segue o estilo do HotPDF, não é compatível byte a byte com veraPDF; o objetivo é permitir que ferramentas posteriores que já consomem JSON do veraPDF se adaptem à saída do HotPDF com remapeamento mínimo de nomes de campos, em vez de aprender um layout completamente diferente

Exemplo

var
  PDF: THotPDF;
begin
  PDF := THotPDF.Create(nil);
  try
    PDF.SavePreflightReport('Input.pdf', 'PreflightReport.txt');
    PDF.SavePreflightReport('Encrypted.pdf', 'EncryptedReport.txt', 'user-password');
    PDF.SavePreflightReport('Input.pdf', 'PreflightReport.json', '', pfJSON);
    PDF.SavePreflightReport('Input.pdf', 'PreflightReport.html', '', pfHTML);
    PDF.SavePreflightReport('Input.pdf', 'PreflightReport.csv', '', pfCSV);
    PDF.EmbedPreflightReportInPDF('Input.pdf', 'Input-with-report.pdf');
    if not PDF.LoadAndValidatePreflightReport(
      'Input-with-report.pdf', OriginalReport, CurrentReport)
    then
      WriteLn('Embedded preflight report no longer matches the source.');
  finally
    PDF.Free;
  end;
end;

Consulte também

• Preflight Cookbook
• Preflight API Map
• LoadFromFile
• GetLoadedPageBox
• Loaded form field methods