BLACKFIRE69
03-09-2020, 05:52
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
.
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
.