Game files integrity check - XHash Library

[BLACKFIRE69]

XHashEx v2.0
File Hashing & Checksum Verification API for Inno Setup
84 algorithms · multi-threaded · Win32 DLL (32 & 64-bit Windows) · by BLACKFIRE69

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━

▌ OVERVIEW
XHashEx is a lightweight, high-performance hashing library crafted for Inno Setup. It generates and verifies checksum files for entire folders, hashes single files, and exposes 84 hashing algorithms — from fast CRC32/XXHash to the full cryptographic suite (SHA-2, SHA-3, BLAKE2/3 …) — all from a single DLL with live per-file and overall progress tracking. Ideal for verifying the integrity of downloaded payloads, large data sets, or already-installed files before continuing an installation.

▌ TECHNICAL SPECIFICATIONS

• Version — v2.0
• Author — BLACKFIRE69
• Build — 2026-Jun
• Compatibility — Inno Setup v6.0 or later (Required)
• Platform — Win32 DLL (runs on 32-bit and 64-bit Windows)

▌ WHAT'S NEW (v2.0)

⚠ BREAKING CHANGE — No Backward Compatibility
Every exported function was renamed with an XH_ prefix and a cleaner name (e.g. CalculateHashesForDir → XH_GenerateDir). v1.x scripts will not work until imports are updated — swap to the bundled XHashEx.iss header. The ProcessMessages export was removed entirely; the DLL pumps the message queue itself.

✦ Multi-Threading Support (NEW)
Hash many files in parallel via a worker-thread pool, count selectable at runtime with XH_SetThreadCount (XH_THREADS_SINGLE / N / XH_THREADS_AUTO). OFF by default — opt in with one call.

✦ Light Callback Mode (NEW)
On folders with tens of thousands of files, per-file callback crossings into Pascal Script dominate the runtime, not the hashing. XH_SetCallbackMode(XH_CALLBACK_LIGHT) keeps directory runs fast in BOTH thread modes: failures/missing/final file are always reported, plus a ~10×/s sampled tick — the log still records every file. OFF by default.

✦ Measured Performance (28,036 files · xxHash32 · SATA SSD · Windows 11)

╭───────────────────┬──────────────────────┬──────────────┬───────────╮
│ Mode              │ Duration v1.4+ (Mar) │ Duration 2.0 │ Speedup   │
├───────────────────┼──────────────────────┼──────────────┼───────────┤
│ ST generation     │         7 min 32 sec │       32 sec │ ~14×      │
│ ST verification   │         8 min 40 sec │       35 sec │ ~15×      │
│ MT generation     │         5 min 36 sec │       26 sec │ ~13×      │
│ MT verification   │         6 min 13 sec │       28 sec │ ~13×      │
╰───────────────────┴──────────────────────┴──────────────┴───────────╯

At that rate the SATA SSD itself is the limit (~420–500 MB/s); NVMe raises the ceiling further.

✦ Byte-Weighted Progress (NEW)
Overall progress reflects the share of BYTES hashed, so the bar moves smoothly even when file sizes vary wildly. Toggle with XH_SetProgressMode (on by default).

✦ Accurate MT Progress + Instant Pause
In MT runs the overall percent tracks exactly what's reported to your callback — it reaches 100% precisely when the run finishes — and Pause/Resume/Cancel take effect immediately even under heavy load.

✦ Significant Performance Improvements
Throughput scales with cores (auto-capped to keep disk access sane), no extra per-file metadata pass before hashing, each worker reuses its hash object across files, and the DLL pumps the message queue itself.

✦ New High-Performance File Search Engine
The old file-search code is replaced with a faster wide-API scanner customized for hashing (lean path-only mode), pre-compiled wildcard masks, and full case-insensitive $"regex" support.

✦ Expanded Algorithm Set
The full cryptographic suite is now exposed — 80+ algorithms total (added SHA-224/384, SHA-3/Keccak, RIPEMD-160/320, WhirlPool, BLAKE2B/2SP/2BP, GOST, Snefru, Tiger/Haval variants …).

✦ Unicode Fixes
Checksum and log files are written/read as UTF-8, so non-Latin file names (Cyrillic, CJK …) round-trip correctly instead of being mangled.

✦ Performance Upgrade
Read buffer and hash object reused across files (no per-file alloc), files opened once with sequential-scan I/O, and progress callbacks throttled to whole-percent changes.

✦ Bug Fixes & Stability
Fixed a UI-freeze regression during long operations, corrected progress reporting on the verification path, and various smaller fixes.

✦ Refreshed Example & Docs
A new, comprehensive Inno Setup 6 demo (XHashEx_Example.iss) with a Multi-threaded toggle (paired with light callback mode), a live Elapsed / Speed / ETA readout, and a final Duration + average-throughput summary — plus an updated quick-reference.

▌ KEY FEATURES

✦ Directory Checksum Generation
Recursively hash an entire folder into a single checksum file (.md5/.sha1/.sha256/.sfv …), one algorithm per run.

✦ Checksum Verification
Verify files against a checksum file with an explicit algorithm, or in auto-detect mode (CRC32/MD5/SHA1/SHA256/SHA512) for mixed-algorithm lists.

✦ Single-File Hashing
Compute and return the digest of one file, or verify it against a known hash.

✦ Powerful File Selection (Masks)
Include/Exclude using wildcards, sub-folders, @list files, and case-insensitive $"regex" patterns — mix freely with '|'.

✦ Multi-Threaded Hashing
Optionally hash in parallel across a worker-thread pool (selectable count, or auto). Result callbacks stay on your calling thread — safe to enable with no other code changes.

✦ Live Progress Tracking
Per-file %, overall % (byte-weighted by default), file size, bytes processed, total file count, per-file status (Ok / Bad / Missing).

✦ Process Control
Pause, Resume, and Stop a running operation safely at any point.

✦ Customizable Logging
Optional log file with fully customizable log message strings.

✦ Checksum File Comments
Write custom comment lines into the header of the generated checksum file.

✦ Attribute Control
Optionally include hidden and/or system files when scanning.

✦ Performance Tuning
Adjustable read buffer (default 4 MB) for max throughput on very large files; hash object + buffer reused across files.

✦ Full Unicode Support
Non-Latin file names handled correctly; checksum and log files written as UTF-8.

✦ Previous-Hash Cache
Append new results to existing in-memory hashes to build cumulative checksum files across multiple passes.

✦ Bonus: File Search / Enumeration API
A built-in wide-API file scanner (wfs_*) for listing files/directories by the same mask/regex syntax, with optional per-file size, attributes, and CRC32.

▌ SUPPORTED ALGORITHMS (80+ total)

╭───────────────────┬──────────────────────────────────────────────────────╮
│ Group             │ Algorithms                                           │
├───────────────────┼──────────────────────────────────────────────────────┤
│ Checksum          │ CRC32                                                │
│ MD                │ MD2, MD4, MD5                                        │
│ SHA-1 / SHA-2     │ SHA0, SHA1, SHA-224/256/384/512, SHA-512/224, /256   │
│ SHA-3 / Keccak    │ SHA3-224/256/384/512, Keccak-224/256/288/384/512     │
│ RIPEMD            │ RIPEMD, RIPEMD-128/160/256/320                       │
│ BLAKE             │ BLAKE2S, BLAKE2B, BLAKE2SP, BLAKE2BP, BLAKE3         │
│ Tiger             │ Tiger & Tiger2 (3/4/5 rounds x 128/160/192)          │
│ Haval             │ Haval (3/4/5 rounds x 128/160/192/224/256)           │
│ Other crypto      │ WhirlPool, GOST, GOST R 34.11-2012, HAS-160, Snefru, │
│                   │ Grindahl, Panama, RadioGatun                         │
│ Fast / non-crypto │ MurmurHash3, XXHash32                                │
╰───────────────────┴──────────────────────────────────────────────────────╯

Each algorithm has a numeric id (1..84), listed with XH_* constants in XHashEx.iss. Auto-detect verification supports only CRC32/MD5/SHA1/SHA256/SHA512; others need their explicit id.

▌ MASKS (Include / Exclude)
Matched against the file's RELATIVE path + name, combined with '|'. Blank or '*' means all files.

*.dll|*.exe                  wildcards / extensions
images\png\*                 a sub-folder
G????info.*                  ? = single char
@"IncludeFiles.txt"          @list file (one mask per line)
$"^setup.*\.exe$"            case-insensitive regex
*.dll|@list.txt|$"\d{4}"     mix all three

▌ EXPORTED API FUNCTIONS
(v1.x names in parentheses)

• Generation — XH_GenerateDir (CalculateHashesForDir), XH_GenerateDirEx, XH_HashFile (CalculateFileHash)
• Verification — XH_VerifyDir (VerifyHashesFromFile), XH_VerifyDirEx, XH_VerifyDirAuto, XH_VerifyDirAutoEx, XH_VerifyFile
• Process Control — XH_Pause, XH_Resume, XH_Stop, XH_GetStatus
• Configuration — XH_SetThreadCount, XH_SetCallbackMode, XH_SetProgressMode, XH_SetMaxProgress, XH_SetBufferSize, XH_GetBufferSize, XH_SetIncludeAttribs, XH_SetLogFile, XH_SetLogMessage, XH_HideComments, XH_AddComment, XH_ClearComments
• Results & Logging — XH_GetLog, XH_ClearLog, XH_GetHashText, XH_ClearHashText, XH_GetVerifiedFileCount
• Utility — XH_ByteOrTb
• File Search (wfs_*) — wfs_FindFiles / wfs_FindFilesEx / wfs_FindFilesExFast, wfs_FileCount, wfs_PickFile, wfs_PickFileList, wfs_DirCount, wfs_PickDir, wfs_SaveFileList, wfs_SaveDirList, wfs_FindFree

▌ QUICK START EXAMPLES

Example 1 — Generate a checksum file for a folder

#include "XHashEx.iss"

function MyProgress(FileName: WideString; FileSize: Extended;
  FileProgress, TotalProgress, TotalFiles, FileCounted, StatusCode: Integer): Boolean;
begin
  // update your UI here ... (no ProcessMessages needed)
  Result := False;   // return True to abort
end;

if XH_GenerateDir(
     ExpandConstant('{app}\checksums.sha256'),
     ExpandConstant('{app}'),
     XH_SHA256, @MyProgress) = XH_PROCESS_DONE then
  Log('Checksum file created.');

Example 2 — Verify a checksum file

case XH_VerifyDir(
       ExpandConstant('{app}\checksums.sha256'),
       ExpandConstant('{app}'),
       XH_SHA256, 0, True, @MyProgress) of
  XH_PROCESS_DONE:          Log('All files verified.');
  XH_INVALID_CHECKSUM_FILE: Log('Checksum file missing/invalid.');
  XH_PROCESS_ABORTED:       Log('Cancelled by user.');
end;

Example 3 — Verify a mixed-algorithm list (auto-detect)

// auto-detect handles CRC32/MD5/SHA1/SHA256/SHA512
XH_VerifyDirAuto(
  ExpandConstant('{app}\hash_mixed.md5'),
  ExpandConstant('{app}'),
  0, False, @MyProgress);   // PreviousFileCount, no log file

Example 4 — Hash a single file

Digest := XH_HashFile(
  ExpandConstant('{app}\game.exe'), XH_XXHASH_32, @MySingleProgress);
MsgBox('XXHash32: ' + Digest, mbInformation, MB_OK);

Example 5 — Generate with masks (wildcards + regex), hidden files included

XH_SetIncludeAttribs(True, False);   // include hidden, not system
XH_SetBufferSize(4096);              // 4 MB read buffer

XH_GenerateDirEx(
  ExpandConstant('{app}\data.md5'),
  ExpandConstant('{app}'),
  '*.dll|*.exe|$"^data\d+\.bin$"',    // include masks
  '*.log|$"\.(tmp|bak)$"',            // exclude masks
  True, False, XH_MD5, @MyProgress);

▌ DISTRIBUTION FILES

• XHashEx.dll — the hashing library (single DLL)
• XHashEx.iss — header for Inno Setup (constants, types, imports)
• XHashEx_Example.iss — full working demo (generate / verify / single file, algorithm picker, masks, pause/resume, log)
• _Usage.txt — quick reference for masks and algorithm ids

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━

Feedback, bug reports and suggestions are welcome. Enjoy!
— BLACKFIRE69

.