API Reference

Complete reference for the public API of the CHDSharp package. All types live in the CHDSharp namespace (models in CHDSharp.Models, address helpers in CHDSharp.Utils).

Chd — static class

Entry point for verification, quick checks, and global settings.

ChdFile — random-access reader

public sealed class ChdFile : IDisposable, IAsyncDisposable

Open a CHD once, then read hunks or byte ranges on demand. Not thread-safe — serialize all calls on one instance.

Static factory methods

All overloads seek from the start. Failure codes: Chderrfilenotfound, Chderrcannotopenfile, Chderrinvalidparameter, Chderrinvalidfile, Chderrreaderror, Chderrrequiresparent, Chderrinvalidparent, Chderrunsupportedversion, Chderrinvaliddata. Cancellation throws OperationCanceledException.

Instance methods

Properties

ChdResult — verification result (record)

Supports deconstruction: var (err, ver, sha1, md5) = result;

ChdHeaderInfo — full header DTO (record)

Returned by Chd.ReadHeader(...). A snapshot of everything in the CHD header, parsed without opening the file for hunk reads and without keeping a file handle open.

ChdProgress — long-operation progress (record)

Pass an IProgress<ChdProgress> to Chd.CheckFile, Chd.CheckFileWithParent, ChdFile.ReadAllBytes, ChdFile.EnumerateHunks, or ChdFile.ExtractToDirectory to receive a report after each decompressed hunk. Wrap it in new Progress<ChdProgress>(...) for UI binding or logging.

var progress = new Progress<ChdProgress>(p =>
    Console.WriteLine($"{p.Percent:F0}% — {p.BytesProcessed:N0}/{p.TotalBytes:N0} bytes ({p.Elapsed.TotalSeconds:F1}s)"));

var result = Chd.CheckFile(File.OpenRead("game.chd"), "game.chd", deepCheck: true, progress);

For Chd.CheckFile(deepCheck: true), reports arrive in hunk order from the internal hashing thread — an IProgress<T> built with new Progress<ChdProgress>(...) marshals them back to the capturing context automatically. All parameters default to null, so existing callers are unaffected.

Cancellation

Every long-running operation accepts an optional trailing CancellationToken (default default) and throws OperationCanceledException when cancellation is requested: Chd.CheckFile, Chd.CheckFileWithParent, ChdFile.Open/OpenAsync (all overloads), ReadHunk/ReadHunkAsync, Read/ReadAsync, ReadAllBytes, and ExtractToDirectory/ExtractToDirectoryWithReporting. Async twins pass the token to Task.Run too, so a pre-cancelled token yields a cancelled task.

For CheckFile(deepCheck: true) the caller token is linked into the verification pipeline’s internal CancellationTokenSource (CreateLinkedTokenSource), so cancellation stops the producer/workers/hasher immediately; the method then throws OperationCanceledException rather than returning a bogus hash-mismatch error over partial data. Cancellation is never swallowed into a ChdError result by extraction — it always propagates as OperationCanceledException.

using var cts = new CancellationTokenSource();
var result = Chd.CheckFile(File.OpenRead("game.chd"), "game.chd", deepCheck: true, cancellationToken: cts.Token);

ChdMetadataEntry — metadata record

public record ChdMetadataEntry(string Tag, byte[] Data)

Equality is based on Tag + Data only (the Flags byte is excluded).

ChdTrackInfo — CD/GD-ROM track (class)

CdRomAddress — MSF ↔ LBA conversion (static)

CHDSharp.Utils namespace. Pure math, no dependencies. MSF values are BCD-encoded as found in CD sector headers and drive addressing: 0x02 = 2 minutes, 0x10 = 10 minutes. Per the Red Book, LBA 0 corresponds to MSF 00:02:00 (the 2-second lead-in offset); the Alt variants omit that offset for systems (Sega CD, PC Engine) that address frames relative to the start of the disc data.

Throws ArgumentOutOfRangeException when a byte is not valid BCD (a nibble above 9), when the resulting MSF position would be negative, or when the minute field would exceed 99 (the BCD limit).

using CHDSharp.Utils;

int lba = CdRomAddress.MsfToLba(0x00, 0x02, 0x00);      // 0
var (m, s, f) = CdRomAddress.LbaToMsf(8850);            // (0x02, 0x00, 0x00)
var (altM, altS, altF) = CdRomAddress.LbaToMsfAlt(150); // (0x00, 0x02, 0x00)

ExtractResult / TrackExtractResult

ExtractResult (record): CreatedFiles (IReadOnlyList<string>), TrackResults (IReadOnlyList<TrackExtractResult>), Error (ChdError), IsCompleteSuccess, HasTrackFailures.

TrackExtractResult (record): TrackNumber, FilePath (string?), Error, IsSuccess.

Enums

ChdCodec — 4-char codec tags

None = 0, Zlib (zlib), Lzma (lzma), Huffman (huff), Flac (flac), Zstd (zstd), Cdzlib (cdzl), Cdlzma (cdlz), Cdflac (cdfl), Cdzstd (cdzs), Avhuff (avhu), Error.

ChdTrackType

Mode1 = 0, Mode1Raw = 1, Mode2 = 2, Mode2Form1 = 3, Mode2Form2 = 4, Mode2FormMix = 5, Mode2Raw = 6, Audio = 7.

ChdSubType

None = 0, Normal = 1, Raw = 2.

CompressionType — per-hunk map entry types

Compressiontype0..3 (codec slots), Compressionnone, Compressionself, Compressionparent, Compressionrlesmall, Compressionrlelarge, Compressionself0/1, Compressionparentself, Compressionparent0/1, Compressionmini, Compressionerror, Compressionzero, Compressiontype2Nd.

ChdError

The complete 29-value error enum — see Error Codes. Every value has a human-readable message via the GetMessage() extension:

ChdError err = ChdFile.Open("missing.chd", out _);
Console.WriteLine(err.GetMessage());   // "File not found"

Extension methods

ChdErrorExtensions.GetMessage(this ChdError) — human-readable error text. ChdSharp also exposes big-endian helpers (BigEndian/EndianHelpers) internally for the test suite.