Class Chd

Namespace

CHDSharp

Assembly

CHDSharpLib.dll

Provides static methods for validating, inspecting, and verifying CHD (Compressed Hunks of Data) files using parallel decompression. Supports CHD format versions 1-5 and all MAME codecs (zlib, LZMA, Huffman, FLAC, Zstd, AVHuff and the CD variants).

public static class Chd

Inheritance

object

Chd

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Examples

using Stream s = File.OpenRead("game.chd");
ChdResult result = Chd.CheckFile(s, "game.chd", deepCheck: true);
if (result.IsSuccess)
    Console.WriteLine($"V{result.Version} SHA1={result.Sha1Hex}");
else
    Console.WriteLine(result.Error.GetMessage());

Remarks

Use CheckFile(Stream, string, bool, IProgress<ChdProgress>?, CancellationToken) for full (parallel) verification of a standalone CHD, CheckFileWithParent(string, string?, IProgress<ChdProgress>?, CancellationToken) for child (differential) CHDs, IsChdFile(string) / CheckHeader(Stream, out uint, out uint) for fast header-only checks, and ReadHeader(string, out ChdHeaderInfo?) for the full parsed header without opening the file for reads. For random access to decompressed data use ChdFile instead.

Properties

LoggerFactory

Gets or sets the ILoggerFactory used for internal logging. Can be set (or changed) at any time; loggers resolve the factory lazily. If not set, logging is silently discarded.

public static ILoggerFactory? LoggerFactory { get; set; }

Property Value

ILoggerFactory

TaskCount

Number of parallel decompression tasks used during verification (default 8). Must be between 1 and 64. Changing it affects subsequent CheckFile(Stream, string, bool, IProgress<ChdProgress>?, CancellationToken) calls; verifications already in progress keep the value they started with.

public static int TaskCount { get; set; }

Property Value

int

Exceptions

ArgumentOutOfRangeException

Thrown when the value is less than 1 or greater than 64.

Methods

CheckFile(Stream, string, bool, IProgress<ChdProgress>?, CancellationToken)

Validates a CHD file from a Stream using parallel decompression and hash verification. Returns a ChdResult with version, SHA1, and MD5 hashes.

public static ChdResult CheckFile(Stream s, string filename, bool deepCheck, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

s Stream

A readable, seekable stream positioned at the start of the CHD file.

filename string

The filename associated with the stream, used only for logging.

deepCheck bool

If true, performs full decompression of every hunk plus SHA1/MD5 hash verification (using up to TaskCount parallel workers); if false, only the header is validated.

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk during deep verification. null (default) disables progress reporting.

cancellationToken CancellationToken

A token to cancel deep verification. OperationCanceledException is thrown if cancellation is requested while hunks are being decompressed or hashed.

Returns

ChdResult

A ChdResult with the verification result, CHD version, and header hashes.

Remarks

This method does not handle differential (parent/child) CHDs; it returns Chderrrequiresparent for those. Use CheckFileWithParent(string, string?, IProgress<ChdProgress>?, CancellationToken) instead.

CheckFile(Stream, string, bool, out uint?, out byte[]?, out byte[]?, IProgress<ChdProgress>?, CancellationToken)

Validates a CHD file from a Stream and returns the CHD version plus the SHA1/MD5 hashes stored in its header.

public static ChdError CheckFile(Stream s, string filename, bool deepCheck, out uint? chdVersion, out byte[]? chdSha1, out byte[]? chdMd5, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

s Stream

A readable, seekable stream positioned at the start of the CHD file.

filename string

The filename associated with the stream, used only for logging.

deepCheck bool

If true, performs full decompression of every hunk plus SHA1/MD5 hash verification (using up to TaskCount parallel workers); if false, only the header is validated.

chdVersion uint?

When this method returns, contains the CHD version (1-5), or null if the header was invalid.

chdSha1 byte[]

When this method returns, contains the SHA1 hash from the header, or null if not available (V1/V2).

chdMd5 byte[]

When this method returns, contains the MD5 hash from the header, or null if not available (V4/V5).

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk during deep verification. null (default) disables progress reporting.

cancellationToken CancellationToken

A token to cancel deep verification. OperationCanceledException is thrown if cancellation is requested while hunks are being decompressed or hashed.

Returns

ChdError

Chderrnone on success; otherwise an error code describing the failure.

CheckFileAndRepair(string, out bool, IProgress<ChdProgress>?, CancellationToken)

Fully verifies a CHD and, when the header SHA-1 hash fields are present but do not match the recomputed values, repairs them in place (chdman verify --fix parity): V3's sha1 field (raw data hash), V4/V5's rawsha1 field, and V4/V5's combined sha1 field (recomputed as SHA-1 of the raw hash plus the sorted checksummed metadata hashes, MAME compute_overall_sha1 parity). Only the header hash fields are patched — the rest of the file is untouched, exactly like chdman. V1/V2 files (MD5 only) and V5 uncompressed CHDs (no hash fields) are reported as verified with nothing to fix.

public static ChdResult CheckFileAndRepair(string filename, out bool repaired, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file to verify and repair.

repaired bool

When this method returns, true if a hash mismatch was found and the header was rewritten; false when the hashes already matched (or no hash fields exist to repair).

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk during the full verification.

cancellationToken CancellationToken

A token to cancel the verification.

Returns

ChdResult

A ChdResult with the verification result. On success the computed (repaired) hashes are available in Sha1.

Exceptions

OperationCanceledException

Thrown when cancellationToken is cancelled while hunks are being decompressed or hashed.

CheckFileWithParent(string, ParentResolver?, IProgress<ChdProgress>?, CancellationToken)

Verifies a (possibly child) CHD file by decompressing all hunks and comparing hashes, resolving parent references lazily via a ParentResolver callback.

public static ChdResult CheckFileWithParent(string filename, ParentResolver? parentResolver, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file to verify.

parentResolver ParentResolver

A callback that resolves parent CHDs by SHA1/MD5 hash, or null to fail on child CHDs.

progress IProgress<ChdProgress>

An optional progress reporter, or null.

cancellationToken CancellationToken

A token to cancel verification.

Returns

ChdResult

A ChdResult with the verification result, CHD version, and header hashes.

CheckFileWithParent(string, ParentResolver?, out uint?, out byte[]?, out byte[]?, IProgress<ChdProgress>?, CancellationToken)

Verifies a (possibly child) CHD file by decompressing all hunks and comparing hashes, resolving parent references lazily via a ParentResolver callback. Also returns the header version and hashes.

public static ChdError CheckFileWithParent(string filename, ParentResolver? parentResolver, out uint? chdVersion, out byte[]? chdSha1, out byte[]? chdMd5, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file to verify.

parentResolver ParentResolver

A callback that resolves parent CHDs by SHA1/MD5 hash, or null to fail on child CHDs.

chdVersion uint?

When this method returns, contains the CHD version (1-5), or null if the file could not be opened.

chdSha1 byte[]

When this method returns, contains the SHA1 hash from the header, or null if not available.

chdMd5 byte[]

When this method returns, contains the MD5 hash from the header, or null if not available.

progress IProgress<ChdProgress>

An optional progress reporter, or null.

cancellationToken CancellationToken

A token to cancel verification.

Returns

ChdError

Chderrnone on success; otherwise an error code describing the failure.

CheckFileWithParent(string, string?, IProgress<ChdProgress>?, CancellationToken)

Fully verifies a (possibly child/differential) CHD by decompressing the whole image and comparing the computed hashes against the values stored in the header, resolving parent references against the CHD at parentFilename.

public static ChdResult CheckFileWithParent(string filename, string? parentFilename, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file to verify.

parentFilename string

Path to the parent CHD, or null/empty for a standalone CHD.

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk. null (default) disables progress reporting.

cancellationToken CancellationToken

A token to cancel verification. OperationCanceledException is thrown if cancellation is requested while hunks are being read.

Returns

ChdResult

A ChdResult with the verification result, CHD version, and header hashes.

Remarks

Unlike CheckFile(Stream, string, bool, IProgress<ChdProgress>?, CancellationToken) , this method is single-threaded but supports parent/child CHD chains. Returns Chderrinvalidparent when the supplied parent does not match, and Chderrrequiresparent when the CHD is a child and no parent was supplied.

CheckFileWithParent(string, string?, out uint?, out byte[]?, out byte[]?, IProgress<ChdProgress>?, CancellationToken)

Fully verifies a (possibly child/differential) CHD by decompressing the whole image and comparing the computed hashes against the values stored in the header, resolving parent references against the CHD at parentFilename. Also returns the header version and hashes.

public static ChdError CheckFileWithParent(string filename, string? parentFilename, out uint? chdVersion, out byte[]? chdSha1, out byte[]? chdMd5, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file to verify.

parentFilename string

Path to the parent CHD, or null/empty for a standalone CHD.

chdVersion uint?

When this method returns, contains the CHD version (1-5), or null if the file could not be opened.

chdSha1 byte[]

When this method returns, contains the SHA1 hash from the header, or null if not available.

chdMd5 byte[]

When this method returns, contains the MD5 hash from the header, or null if not available.

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk. null (default) disables progress reporting.

cancellationToken CancellationToken

A token to cancel verification. OperationCanceledException is thrown if cancellation is requested while hunks are being read.

Returns

ChdError

Chderrnone on success; otherwise an error code describing the failure.

CheckHeader(Stream, out uint, out uint)

Reads and validates the CHD file header signature ("MComprHD") and version.

public static bool CheckHeader(Stream file, out uint length, out uint version)

Parameters

file Stream

The stream, positioned at the start of the CHD file (byte 0).

length uint

When this method returns, contains the header length in bytes declared by the file; 0 if invalid.

version uint

When this method returns, contains the CHD version number (1-5); 0 if invalid.

Returns

bool

true if the signature is valid, the version is recognized (1-5), and the declared header length matches that version; otherwise false.

Remarks

The stream is advanced past the 16-byte signature. Unknown versions and truncated streams return false rather than throwing.

Classify(string, out string?)

Quickly classify a CHD file as CD, DVD, HDD, GD-ROM, or unknown without full decompression.

public static ChdError Classify(string filename, out string? classification)

Parameters

filename string

Path to the CHD file.

classification string

When this method returns, contains "cd", "dvd", "hdd", "gd-rom", or null for unknown types.

Returns

ChdError

Chderrnone on success; otherwise an error code.

ComputeHashes(string, ChdHashType, string?, bool, IProgress<ChdProgress>?, CancellationToken)

Computes hash digests over a CHD's decompressed content (CHDlite hash_content parity). For CD/GD-ROM images with perTrack set, one hash per track is returned (track boundaries from Tracks); otherwise a single whole-image hash is returned. Reading and hashing happen in one sequential pass.

public static IReadOnlyList<ChdHashResult> ComputeHashes(string filename, ChdHashType types, string? parentFilename = null, bool perTrack = false, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file (standalone; child CHDs need parentFilename).

types ChdHashType

The hash algorithms to compute (bitwise OR of ChdHashType).

parentFilename string

Parent CHD path for a child CHD, or null for standalone.

perTrack bool

For CD/GD-ROM images, hash each track separately instead of the whole image.

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk.

cancellationToken CancellationToken

A token to cancel the hashing. OperationCanceledException is thrown if cancellation is requested.

Returns

IReadOnlyList<ChdHashResult>

One ChdHashResult per hashed region (track or whole image), in order. Empty when types is None.

Exceptions

InvalidDataException

The CHD cannot be opened or a hunk fails to decompress.

ComputeHashesWithReporting(string, ChdHashType, string?, bool, IProgress<ChdProgress>?, CancellationToken)

Computes hash digests over a CHD's decompressed content, returning a ChdHashComputeResult with the error code instead of throwing on failure. For CD/GD-ROM images with perTrack set, one hash per track is returned; otherwise a single whole-image hash is returned.

public static ChdHashComputeResult ComputeHashesWithReporting(string filename, ChdHashType types, string? parentFilename = null, bool perTrack = false, IProgress<ChdProgress>? progress = null, CancellationToken cancellationToken = default)

Parameters

filename string

Path to the CHD file (standalone; child CHDs need parentFilename).

types ChdHashType

The hash algorithms to compute (bitwise OR of ChdHashType).

parentFilename string

Parent CHD path for a child CHD, or null for standalone.

perTrack bool

For CD/GD-ROM images, hash each track separately instead of the whole image.

progress IProgress<ChdProgress>

An optional IProgress<T> receiving a ChdProgress report after each decompressed hunk.

cancellationToken CancellationToken

A token to cancel the hashing. OperationCanceledException is thrown if cancellation is requested.

Returns

ChdHashComputeResult

A ChdHashComputeResult with the error code and hash results.

IsChdFile(string)

Quickly checks whether a file at the given path has a valid CHD header. Only the 16-byte header signature is read; no decompression is performed.

public static bool IsChdFile(string path)

Parameters

path string

Filesystem path to a potential CHD file.

Returns

bool

true if the file exists, is readable, and has a valid CHD header; otherwise false. Never throws.

IsChdFile(string, out uint)

Quickly checks whether a file at the given path has a valid CHD header. Only the 16-byte header signature is read; no decompression is performed.

public static bool IsChdFile(string path, out uint version)

Parameters

path string

Filesystem path to a potential CHD file.

version uint

When this method returns, contains the CHD version number (1-5) if valid; otherwise 0.

Returns

bool

true if the file exists, is readable, and has a valid CHD header; otherwise false. Never throws.

ReadHeader(Stream, out ChdHeaderInfo?)

Reads and parses the full CHD header from an existing seekable stream (libchdr chd_read_header_file parity). The stream is seeked as needed and left open.

public static ChdError ReadHeader(Stream stream, out ChdHeaderInfo? header)

Parameters

stream Stream

A readable, seekable stream containing a CHD file.

header ChdHeaderInfo

When this method returns, contains the parsed header information on success, or null on error.

Returns

ChdError

Chderrnone on success; Chderrinvalidparameter if the stream is not readable/seekable; Chderrinvalidfile if it is not a CHD; Chderrreaderror on IO failure; otherwise a header parse/validation error.

ReadHeader(string, out ChdHeaderInfo?)

Reads and parses the full CHD header from the file at filename without opening it for hunk reads (libchdr chd_read_header parity). The file is opened, the header is parsed, and the file is closed again — no file handle is kept alive.

public static ChdError ReadHeader(string filename, out ChdHeaderInfo? header)

Parameters

filename string

Path to the CHD file to read.

header ChdHeaderInfo

When this method returns, contains the parsed header information on success, or null on error.

Returns

ChdError

Chderrnone on success; Chderrinvalidparameter if filename is null/empty; Chderrfilenotfound if the file does not exist; Chderrcannotopenfile if it cannot be opened; Chderrinvalidfile if it is not a CHD; otherwise a header parse/validation error.

Remarks

Unlike Open(string, out ChdFile?, CancellationToken), this performs no hunk-map linking, codec setup, or parent resolution, and does not retain a stream. Use it to inspect a CHD (version, sizes, codecs, hashes, parent linkage) cheaply.

ReadHeaderAsync(string)

Reads and parses the full CHD header from the file at filename without opening it for hunk reads (libchdr chd_read_header parity). The file is opened, the header is parsed, and the file is closed again — no file handle is kept alive.

public static Task<(ChdError error, ChdHeaderInfo? header)> ReadHeaderAsync(string filename)

Parameters

filename string

Path to the CHD file to read.

Returns

Task<(ChdError error, ChdHeaderInfo header)>

Chderrnone on success; Chderrinvalidparameter if filename is null/empty; Chderrfilenotfound if the file does not exist; Chderrcannotopenfile if it cannot be opened; Chderrinvalidfile if it is not a CHD; otherwise a header parse/validation error.

Remarks

Unlike Open(string, out ChdFile?, CancellationToken), this performs no hunk-map linking, codec setup, or parent resolution, and does not retain a stream. Use it to inspect a CHD (version, sizes, codecs, hashes, parent linkage) cheaply.