THotPDF Advanced Workflow Methods

This page collects advanced public THotPDF methods that support loaded-document repair, file-backed rewriting, xref-stream parsing, conformance output, and shaping workflows

Prefer the task-focused pages such as page operation methods, loaded form field methods, utility methods, CMS validation reports, PDF/UA-2 structure, and ShapingFeatures for common application code

Loaded Document Resolution

Method	Usage
`DoPageOperationProgress`	Dispatches page-operation progress through the configured progress event
`ResolveLoadedObject`	Resolves a loaded object reference to the object that page operations can inspect or copy
`ResolveLoadedDictionary`	Resolves a loaded object reference and returns it as a dictionary when possible
`ResolveLoadedArray`	Resolves a loaded object reference and returns it as an array when possible
`EnsureLoadedRootIndex`	Ensures that the loaded catalog index is known before object-graph operations continue
`MaterializeLazyStreams`	Loads deferred stream data before a full rewrite or object-level copy operation
`FindLoadedFormFieldByIndex`	Returns a loaded AcroForm field dictionary by field index and reports its effective name
`FindLoadedFormFieldByName`	Returns a loaded AcroForm field dictionary by fully qualified field name
`ConfigurePDFVersion`	Applies the currently selected PDF version capabilities to document output settings
`RecoverReloadFEKFromBytes`	Recovers the file encryption key for a reloaded encrypted document when the supplied password matches
`LoadedEncryptVersion`	Reports the encryption revision of the currently loaded document
`IsObjStmMemberObject`	Reports whether an object came from an object stream member and needs object-stream-aware handling
`SyncMaxObjNumFromLoadedObjects`	Rescans loaded objects so newly allocated object numbers do not collide with existing numbers

Direct File State and Rewrite

Method	Usage
`ClearDirectFileState`	Clears a direct-file state record before a handle is reused or released
`GetDirectFileIndex`	Maps a direct-file handle to the state slot used by the Direct File API
`DAFindReplacementIndex`	Finds the replacement entry for an object number in a direct-file state record
`DAReadObjectSource`	Reads stored object source bytes and generation data from direct-file state
`DAStoreObjectSource`	Stores object source bytes in direct-file state for later rewrite
`DAAppendObjectSourceInternal`	Appends a new object body to the direct-file state and returns its allocated object number
`DATryBuildCompressedFileState`	Builds direct-file state for files that use compressed object streams when supported
`DADirectLoadObjectFromBody`	Parses a direct-file object body into a loaded object instance
`DARecoverAES256FileKey`	Recovers an AES-256 file key from an encryption dictionary and password
`DADirectPrepareObjectForAES256Encrypt`	Prepares object dictionaries and streams before AES-256 direct-file encryption
`DADirectDecryptObjectAES256`	Decrypts a parsed direct-file object with the active AES-256 file key
`DAWriteDirectAES256Rewrite`	Writes a direct-file AES-256 encrypt or decrypt rewrite to a target file
`DADirectEncryptFileAES256`	Encrypts an existing file with AES-256 through the direct-file rewrite path
`DADirectDecryptFileAES256`	Decrypts an existing AES-256 file through the direct-file rewrite path
`DAWriteFullRewrite`	Writes a full direct-file rewrite using the current state table

Authenticated Encryption and PDF MAC

Method	Usage
`EncryptFile` with `aesgcm`	Uses the bounded-memory Direct File path to emit PDF 2.0 AESV4 streams with incremental CTR and GHASH processing
`DecryptFile`	Authenticates every AESV4 stream before atomically replacing the requested output file
`AddStandalonePDFMAC`	Adds a fixed 32-byte `KDFSalt`, a direct standalone `AuthCode`, exact full-file `ByteRange` coverage, CMS `AuthenticatedData`, and selectable SHA-2 or SHA-3 document digests
`SignPDFWithPFXAndAttachedPDFMAC`	Creates one encrypted signed revision with a direct `/AttachedToSig` trailer binding, an indirect `SigObjRef`, and a PDF MAC unsigned attribute that authenticates the raw CMS signature value
`ValidatePDFMAC`	Validates standalone or signature-attached locations and returns distinct status values for invalid passwords, malformed data, unsupported algorithms, policy rejection, coverage failures, document modification, signature binding failures, and authentication failures
`ValidatePDFMACChain`	Validates every incremental revision from oldest to newest with cumulative xref indexing and reports the exact revision for a missing, replaced, salt-changed, digest-downgraded, or permission-downgraded PDF MAC

Public-Key Encryption and Signature Evidence

Method	Usage
`AddPubKeyRecipientCertificate`	Builds an AES-256 CMS recipient envelope from an RSA certificate with explicit RSA-OAEP digest and MGF1 policies
`AddPubKeyAgreementRecipient`	Builds P-256, P-384, P-521, X25519, or X448 key-agreement recipient envelopes using X9.63 KDF and AES-256 key wrap
`HPDFCMSBuildCounterSignerInfo`	Creates a countersignature whose signed `messageDigest` binds the parent signature value without a `contentType` attribute
`HPDFVerifyCMSCounterSignatures`	Extracts and verifies every CMS `counterSignature` value against its parent signature bytes
`RenewPAdESLTATimestamp`	Appends a validated RFC 3161 document timestamp while preserving every earlier PDF revision byte-for-byte

PDF/UA-2 Structure

Method	Usage
`AddStructRoleMapNS`	Adds a namespace-aware role mapping with a default PDF 1.7 or explicit target namespace
`SetStructureAttributeName`	Adds or replaces a name-valued attribute in an owner-specific structure attribute dictionary
`SetStructureAttributeNumber`	Adds or replaces an integer-valued structure attribute
`SetStructureTableCellHeaders`	Writes explicit table header identifiers for a header or data cell
`AssociateFileWithStructure`	Associates an indirect Filespec with a structure element
`AddAccessibleFormula`	Creates a Formula structure element with alternative or actual text
`AddAccessibleMathMLFormula`	Creates a Formula with an associated MathML file and MathML namespace child
`ValidatePDFUA2Structure`	Runs bounded one-pass validation and returns typed issues or shared machine-readable findings with clause, object, and page locations
`RepairPDFUA2Structure`	Atomically normalises recoverable PDF/UA-2 namespaces, structure attributes, semantic containers, accessibility text, language inheritance, heading order, and Artifact tags and can report per-finding repair provenance
`ComplianceFindingsToJSON`	Serializes shared PDF/UA-2, PDF/A-4, and PDF/X-6 findings as deterministic versioned JSON

Stable Native C ABI

Export	Usage
`hpdf_document_create`	Creates a validated opaque document handle through a flat `cdecl` boundary
`hpdf_document_load_from_io`	Loads from versioned 64-bit random-access callbacks without a complete-source staging buffer
`hpdf_document_save_to_io`	Streams serialized bytes to a callback and retries partial writes until each chunk is complete
`hpdf_document_page_count`	Returns the loaded page count through a fixed-width output pointer
`hpdf_document_destroy`	Releases a registered handle and rejects repeated destruction

Deterministic Differential Regression

Function	Usage
`HPDFProbeHotPDFDocument`	Produces bounded SHA-256 parse, render, text, or save fingerprints with domain-specific normalization
`HPDFCompareRegressionResultsDeterministic`	Repeats two named engine probes, rejects instability and isolated exceptions, and compares selected domains in fixed order
`HPDFDifferentialRegressionInfoToJSON`	Serializes signatures, instability, errors, counts, engine names, and the input digest as `hotpdf.differential.v1`

Continuous Malformed-PDF Corpus

Function	Usage
`HPDFDefaultCorpusStoreOptions`	Returns bounded minimisation, input, storage, and lock-retry defaults
`HPDFMinimizeAndStoreCorpusCase`	Revalidates and re-minimises matching cases under one process-safe lock, then atomically retains the smallest signature-equivalent PDF
`HPDFCorpusCaseInfoToJSON`	Serializes the stable case ID, failure signature, content digest, and byte count as `hotpdf.corpus.case.v1`

PDF/X-6 Exchange

Method	Usage
`AddPDFX6PageOutputIntent`	Attaches an embedded ICC output intent to one PDF 2.0 page
`AddPDFX6ExternalOutputIntent`	Adds an external PDF/X-6p or N-colourant PDF/X-6n output profile reference at Catalog or page scope
`ValidatePDFX6`	Runs bounded non-mutating PDF/X-6 validation with typed or shared clause-aware object and page diagnostics

XRef Stream and Object Parsing

Method	Usage
`LoadXRefStreamDocument`	Loads a document whose startxref points at an xref stream
`LoadXRefStreamDocumentFromFile`	Loads an xref-stream document from a file and returns key object-location diagnostics
`LoadXRefStreamDocumentEncFromFile`	Loads a password-protected xref-stream document from a file
`XRefProbeObjCount`	Reports how many objects the xref-stream loader registered
`XRefProbeObjNum`	Returns the object number at a zero-based diagnostic index
`XRefProbeCompactCount`	Reports how many compressed objects were materialized from object streams
`XRefProbeType2Mismatches`	Reports object-stream header mismatches found while loading type-2 xref entries
`XRefProbeObjHasKey`	Checks whether a loaded diagnostic object dictionary contains a named key
`XRefProbeObjNameVal`	Returns a name value from a loaded diagnostic object dictionary
`XRefProbeCompactObjNum`	Returns the object number of a compact-object diagnostic entry
`XRefProbeType2EncryptedSkipped`	Reports encrypted object streams skipped by the type-2 object-stream loader
`XRefProbeCountReplacementChars`	Counts Unicode replacement characters in loaded string diagnostics
`XRefProbeObjStringVal`	Returns a string value from a loaded diagnostic object dictionary
`XRefProbeDecryptObjStmSkips`	Reports object-stream member decrypt skips used to avoid double decryption
`TryParseModernPDF`	Attempts the modern PDF parse path for xref-stream and object-stream documents
`CreateBasicPageContent`	Creates minimal page content objects for a loaded or synthesized page
`CreatePDF16PageReference`	Creates a PDF 1.6 page reference using the loaded object graph
`CreateBasicResources`	Creates a minimal resource dictionary for page reconstruction
`CreatePDF16Resources`	Creates a PDF 1.6 resource dictionary for page reconstruction
`ParseSimplePageObject`	Parses a simple page object into the loaded page representation
`ParseRealPageContent`	Parses the original page content stream for a loaded page
`ProcessObjectStreamsForDecompression`	Processes object streams before decompressed objects are inspected or copied
`ScanAndLoadReferencedObjects`	Scans page and resource dictionaries and loads referenced objects
`ForceLoadMissingReferencedObjects`	Loads references that were not materialized during the first parse pass
`FindAllObjectStreams`	Locates object streams in the loaded document graph
`ExtractStreamParameters`	Extracts object-stream length, count, and first-object offset values
`ProcessFlateDecode`	Processes FlateDecode-compressed object-stream bytes
`AnalyzePageObject`	Analyzes a page object body and updates loaded page bookkeeping
`ExtendPageArr`	Adds a page indirect object to the loaded page array
`ParseSimpleDictionary`	Parses a dictionary body into a `THPDFDictionaryObject`
`ParseSimpleArray`	Parses an array body into a `THPDFArrayObject`
`ParseSimpleStream`	Parses a stream body into a `THPDFStreamObject`
`FindAndProcessObjectStream`	Finds an object stream by object number and processes its members
`ExtractObjectFromStream`	Returns a parsed dictionary from a materialized or raw object-stream member
`ExtractRawObjectFromStream`	Extracts raw object bytes from an object stream member
`IsObjectInStream`	Reports whether an object number belongs to an object stream
`GetObjectFromStream`	Returns a parsed object-stream member as a dictionary object
`ParseModernPageObject`	Parses a page object found through the modern object-stream path
`IntelligentDecompress`	Attempts decompression with format-aware fallback logic
`DecompressFlateDecode`	Decompresses FlateDecode stream bytes
`ParseObjectStream`	Parses an object stream header and member table
`ReorderPageArrByPagesTree`	Reorders loaded pages according to the page tree
`GetCorrectPageOrderFromPagesTree`	Builds the page order from the loaded page tree
`GetPageObjectId`	Returns the object number for a loaded page index
`GetPageArrIndexForObjectNumber`	Returns the loaded page-array index for a page object number
`ExtractNumericValue`	Extracts an integer value after a named key in raw object content
`ParseDecompressedObjects`	Parses decompressed object-stream members and returns key object numbers
`LoadCompressedXrefStream`	Loads compressed xref stream data for modern document parsing
`LoadObjectStreamsDirectly`	Loads object streams directly from the current source document
`ParseXrefStreamData`	Parses decoded xref-stream table data
`ProcessObjectStreamObjects`	Processes decompressed object-stream objects from a stream object number

Conformance and Font Output

Method	Usage
`BuildAndApplyUnicodeFontSubset`	Builds the active Unicode font subset and applies the resulting font stream and mapping data
`EnsurePDFUATabsOnAnnotatedPages`	Ensures annotated PDF/UA pages declare the required tab order
`EnsurePDFAOutputIntent`	Checks that a PDF/A output intent is present when the selected PDF/A profile requires one
`EnsurePDFAColorSpaceConsistency`	Checks device colour-space usage against PDF/A output-intent and default-colour-space settings
`EmitDocumentDefaultColorSpaces`	Writes document default colour-space mappings used by PDF/A workflows
`EnsurePDFXOutputIntent`	Checks that a PDF/X output intent is present before output is finalized
`EnsurePDFXPageBoxes`	Checks page boxes required by PDF/X output profiles
`ValidatePDFX6GenerationProfile`	Fails closed when the selected PDF/X-6 generation graph violates the profile
`_FindPAdESDSSStreamByDER`	Finds an existing DSS stream whose DER bytes match a certificate, OCSP response, or CRL while building PAdES VRI references

Advanced Shaping Helpers

Method	Usage
`ApplyArabicGSUBPositional`	Applies Arabic positional GSUB substitutions and maps shaped glyph IDs through synthetic codepoints
`ArabicGSUBShapeToGIDs`	Returns the Arabic GSUB-shaped glyph-ID sequence without emitting text
`ApplyArabicGSUBNativeShaping`	Applies native Arabic GSUB shaping for fonts that provide positional glyph substitutions
`ApplyLatinLigatureFeature`	Applies a named Latin ligature feature such as liga or clig to a Unicode run
`ApplyLatinSingleSubstitutionFeature`	Applies a named Latin single-substitution feature to a Unicode run
`ApplyLatinFractionFeature`	Applies the frac feature to a numeric fraction run when the font supplies the required substitutions
`ApplyArabicGSUBRefinement`	Applies Arabic GSUB ligature refinement after the base Arabic shaping pass
`_ApplyGSUBLookupAt`	Applies one resolved GSUB lookup at a glyph-run position and reports the updated span
`_ApplyGSUBFeatureToRun`	Applies all lookups for one GSUB feature across a glyph run in lookup-list order
`_ApplyGSUBFeatureAtRunPosition`	Applies a GSUB feature at one glyph-run position for position-sensitive shaping passes
`_TibetanShapeSpanToGIDs`	Shapes one Tibetan span to glyph IDs before synthetic-codepoint output
`_GSUBResolveIndicScript`	Chooses the OpenType Indic script tag available in the font, preferring v2 script tags when present
`_IndicShapeSyllableToGIDs`	Applies the Indic GSUB feature chain to one reordered syllable and returns glyph IDs

See also