|
THotPDF Preflight Report Methods
構文
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;
説明
CreatePreflightReport は入力 PDF を読み取り、軽量な構造チェックを含む text report を返します。password overload は、対応する encrypted PDF に対して既存の password-aware load path を使用します。SavePreflightReport は同じ report を target text file に書き込みます
ValidatePDFVT は PDF/VT に絞った validation pass を実行し、必要な marker と structure が存在する場合にのみ True を返します。返される text report は pdfvtid:GTS_PDFVTVersion の XMP claim、PDF/VT metadata namespace、PDF/VT modification date と xmp:ModifyDate の一致、PDF/X base marker、encryption absence、PDF/X output intent、catalog DPartRoot、DPartRootNode、NodeNameList、document part presence、loadable page count、page-level DPart coverage を確認します。PDF/VT と XMP の date properties は、element text または rdf:Description element 上の RDF attribute として書かれていてもかまいません
report は PDF header、EOF marker、最後の %%EOF marker が file の末尾近くにあるか、最後の startxref offset、その offset が xref table または xref stream を指しているか、%%EOF と startxref の marker count、revision marker balance と final marker ordering、trailer または XRef stream marker、loadable page count、encryption state、catalog、page tree、page object marker、MediaBox、information dictionary reference、root reference、indirect object count、indirect object definition count、highest object number、duplicate object number count、object number uniqueness、catalog object count、page tree object count、page object count、page tree declared page count、page tree count/loadable page consistency、page object/loadable page consistency、stream と endstream の balance、stream /Length entry coverage、xref table count、xref subsection count、xref table entry counts、xref free and in-use entry counts、malformed xref row count、xref row validity、xref coverage against object numbers、xref stream count、object stream count、trailer count、trailer /Size、trailer /Size が highest object number を cover しているか、trailer /Root と /Info の indirect references、それらの referenced objects が defined か、trailer /Root が catalog object を target しているか、trailer /ID array entry count と pair structure、trailer /Root、/Info、/ID、/Encrypt の presence、estimated incremental update count、linearization status、loaded page boxes、form field count、resource dictionary count、font resource count、embedded font program count (/FontFile、/FontFile2、/FontFile3)、image XObject count、form XObject count、ColorSpace resource count、annotation count と widget/link annotation subcounts、FlateDecode、DCTDecode、CCITTFaxDecode、JBIG2Decode、LZWDecode、ASCIIHexDecode、ASCII85Decode、RunLengthDecode、JPXDecode の filter chain usage counts、font embedding coverage、annotation count consistency、PDF/A / PDF/X / PDF/UA / Tagged PDF / transparency compliance hints、selected feature flags、JavaScript または action warnings (PDF 1.7 sec 12.6.4 action set 全体: GoTo*、Thread、URI、Sound、Movie、Hide、Named、SubmitForm、ResetForm、ImportData、SetOCGState、Rendition、Trans、GoTo3DView、および legacy JavaScript / Launch / OpenAction / AdditionalActions / EmbeddedFile / RichMedia checks と PDF/A mutual-exclusion warnings を含みます)、warning totals、overall pass/fail summary を確認します。これらの helpers は、files を external standards validators に渡す前の fast in-process checks を意図したもので、full PDF/A、PDF/X、PDF/UA、または ISO 32000 preflight validation engine の代替ではありません
Format overload は pfText (legacy overload と byte-stable な default plain-text path)、pfJSON (CI 向け JSON document)、または pfHTML (inline CSS と severity-coloured rows を含む dashboard-ready な self-contained HTML report) を受け付けます。JSON output は top-level fields の input、size、pdfVersion、xrefStyle、さらに checks、info、hints、warnings arrays と、failed、warnings、result values を持つ summary object に entry を分類します。built-in JSON encoder は "、\、control bytes を escape し、UTF-8 byte sequences はそのまま通します
checks、hints、warnings の各 entry は optional な spec field を持ち、diagnostic が対象にする ISO clause を示します (例: trailer-related checks は ISO 32000-1 sec 7.5.5、PDF/A with JavaScript mutual-exclusion warning は ISO 19005-1 sec 6.6.2)。この mapping は v2.122.0 までに report が出力するすべての check、hint、warning を cover します。pfJSON output structure を記述する formal JSON Schema (draft 2020-12) は Docs/preflight-schema.json に公開されており、downstream consumers は parsing 前に output を validate できます
EmbedPreflightReportInPDF は source PDF の copy を TargetFile に書き込み、legacy text-format preflight report を最後の %%EOF の後ろへ PDF-style comment lines として append します (各行は % で始まります)。append された bytes は object graph の外にあるため PDF readers は無視しますが、archive workflows、text editors、grep-style tools は後続 audit のために embedded report を表示できます。元の object graph、cross-reference table、trailer は変更されません
LoadAndValidatePreflightReport は EmbedPreflightReportInPDF が以前 append した report を抽出し、embedded comment block より前の source bytes に対して現在の preflight algorithm を再実行して InputFingerprint values を比較します。両方の fingerprint が一致した場合、function は True を返し、embedded report が disk 上の現在の file をまだ説明していることを示します。validation が失敗した場合、呼び出し元は OriginalReport と CurrentReport を調べて変更点を diff できます
ComparePreflightReports は 2 つの reports に対して unified-diff-like body を出力します。共通行には two-space prefix、ReportA のみにある行には -、ReportB のみにある行には + が付きます。この algorithm は CreatePreflightReport が生成する well-formed key/value output 向けに調整されており、行順は deterministic です。general-purpose LCS implementation ではありませんが、ほとんど変更のない典型的な reports について compact で読みやすい diff を生成します
RepairPDFFromPreflightReport は damaged PDF に byte-level repairs の保守的な subset を適用します。最後の %%EOF marker より後ろの trailing bytes を削除し、%%EOF がどこにも存在しない場合は append します。少なくとも 1 つの repair が適用された場合、function は True を返します。RepairsApplied は repairs を 1 変更 1 行で列挙します。object-graph repairs (xref tables の rebuild、stream lengths の patch、trailer dictionaries の修正) は意図的に対象外です。この種の修正は partially-recoverable file をかえって recover しにくくする可能性があるため、深い damage には専用の PDF recovery tool を使用してください
AggregatePreflightReports は per-file reports の array を受け取り、1 つの batch summary を生成します。array 内の各 entry は Input、Size、Summary fields について parse され、aggregate は file ごとに 1 行を出力し、passed、failed、warning reports の件数、scan された総 bytes、overall result counts の totals も出力します。PDF directory を処理し、最後に簡潔な summary を 1 つ得たい CI pipelines や shell loops に有用です
LoadPreflightProfile と ApplyPreflightProfile により、analysis を再実行せずに report output を調整できます。profile file は 3 つの optional sections を持つ INI-style format を使用します。[disable-checks] は suppress する check names、[disable-warnings] は suppress する warning names、[options] はすべての Hint line を抑制する hints=false を受け付けます。filtering 後、suppressed entries が Failed と Warnings totals に寄与しないよう Summary line は再計算されます。report の残りは変更されずに通過します
ValidatePreflightProfile は loaded profile の DisableChecks と DisableWarnings lists を走査し、現在の preflight implementation が認識しない name を報告します。より新しいまたは古い HotPDF version 向けに作られた profile file が、name mismatch により何も disable できない状況を検出するのに有用です
GetBuiltInPreflightProfile は common workflows 向けの ready-to-use profile records を返します。認識される names (case-insensitive): default / '' は empty profile を返します。compact は短い report のためにすべての Hint line を disable します。silent-actions は PDF 1.7 sec 12.6.4 action warnings と EmbeddedFile、RichMedia を disable します。これは multimedia または interactive actions を意図的に embed し、preflight report に flag されたくない workflows 向けです。unknown names も empty profile を返します
SavePreflightProfile は THPDFPreflightProfile record を、LoadPreflightProfile が consume するものと同じ format の INI file に書き戻します。この 2 つの functions は well-formed profiles に対して exact inverse なので、呼び出し元は load preset, tweak, save workflow を構築できます。例: P := GetBuiltInPreflightProfile('compact')、P.DisableChecks を編集し、その後 SavePreflightProfile(P, 'tuned.ini') で後から再利用します
CreatePreflightReportWithProfile は既存の CreatePreflightReport、LoadPreflightProfile、ApplyPreflightProfile、format converters を組み合わせる one-stop convenience wrapper です。source PDF、optional password、profile file、target format がすでにある caller は、4 つを chain せず single call を発行できます。empty ProfileFile を渡すと profile step は skip されます
MergePreflightProfiles は 2 つの profiles の deduplicated union を返します。DisableChecks と DisableWarnings は両方の input から names を集め、DisableHints は logical OR になります。preset に project-specific tweaks を重ねる場合に有用です
DiffPreflightProfiles は 2 つの profiles の structural difference を報告します。equivalent の場合は True を返します。それ以外の場合は False を返し、OnlyInA と OnlyInB に check:<name>、warn:<name>、または option:hints=false 形式の newline-separated lines を入れて、どの entries が片側だけにあるかを示します
EmbedPreflightReportAsXMP は EmbedPreflightReportInPDF の archival-friendly variant です。source PDF の copy に、preflight report を XMP / RDF payload (xmlns:hotpdf="http://www.loslab.com/hotpdf/preflight/") を持つ PDF-style comment block として append します。各 report line は hotpdf:<name> element になり、check rows では severity が attribute として保持されます。xpacket markers を scan する XMP-aware tools は embedded report を表示できます。PDF readers は append された bytes が object graph の外にあるため引き続き無視します。これは意図的に spec-compliant XMP integration ではありません。XMP payload は catalog /Metadata entry から参照されないため、catalog reference のみを follow する XMP readers には見えません
ConvertPreflightReportToVeraPDFStyle は HotPDF preflight report を veraPDF の validation output の broad outline に従う JSON document に整形します。top-level の profile field、itemDetails / taskResult / validationResult を含む jobs array、さらに validationResult.details 配下の ruleViolations array を持ちます。veraPDF と wire-compatible ではなく HotPDF-styled です。目的は、すでに veraPDF JSON を consume する downstream tooling が、まったく異なる data layout を学び直すのではなく、最小限の field-name remapping で HotPDF output に適応できるようにすることです
例
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;
関連項目
|