Provides structured, random-access inspection of a Nintendo DS-family image. More...

Inheritance diagram for NdsForge.NdsImage:

Public Member Functions
Stream	OpenRead (NdsRegion region)
	Opens a read-only stream over a validated image region.
async ValueTask	CopyToAsync (NdsRegion region, Stream destination, CancellationToken cancellationToken=default)
	Copies an arbitrary validated image interval without materializing it as one managed array.
async ValueTask	TransformModcryptAreaAsync (NdsModcryptArea area, Stream destination, NdsModcryptContext context, CancellationToken cancellationToken=default)
	Reads one declared DSi modcrypt area and writes its symmetric AES-CTR transformation without loading the region into memory. The supplied context controls key provenance; neither caller-owned destination nor image is closed after completion.
ValueTask< NdsExtractionResult >	ExtractAsync (string destination, NdsExtractionOptions? options=null, CancellationToken cancellationToken=default)
	Safely exports selected image components to a directory.
NdsImageEditor	Edit ()
	Begins an explicit, non-mutating edit session for this source image.
NdsValidationResult	Validate (NdsValidationOptions? options=null)
	Validates checksums, component relationships, bounds, and optional DSi authentication fields.
ValueTask< NdsImageManifest >	CreateManifestAsync (CancellationToken cancellationToken=default)
	Captures a detached, SHA-256-addressed automation manifest without transferring image ownership.
ValueTask< NdsImageDiff >	CompareAsync (NdsImage other, CancellationToken cancellationToken=default)
	Compares this image with another live image at semantic, numeric-identity, and physical-layout levels.
void	Dispose ()
	Synchronously releases the image source and prevents further payload access.
async ValueTask	DisposeAsync ()
	Asynchronously releases the image source and prevents further payload access.

Static Public Member Functions
static async ValueTask< NdsImage >	OpenAsync (string path, NdsReadOptions? options=null, CancellationToken cancellationToken=default)
	Opens an image from a filesystem path without loading the entire file into memory.
static NdsImage	Open (Stream stream, bool leaveOpen=false, NdsReadOptions? options=null)
	Opens an image from a caller-supplied readable, seekable stream.
static async ValueTask< NdsImage >	OpenAsync (Stream stream, bool leaveOpen=false, NdsReadOptions? options=null, CancellationToken cancellationToken=default)
	Asynchronously opens an image from a caller-supplied readable, seekable stream.
static NdsImage	Load (ReadOnlyMemory< byte > data, NdsReadOptions? options=null)
	Loads an image from caller-owned memory.

Properties
NdsHeader	Header `[get]`
	Preserves both typed DS/DSi fields and the raw bytes required for checksums and lossless edits.
NdsFileSystem	FileSystem `[get]`
	Connects navigable FNT paths with every FAT allocation, including unnamed overlay payloads.
IReadOnlyList< NdsOverlay >	Arm9Overlays `[get]`
	Gets ARM9 overlays in table order.
IReadOnlyList< NdsOverlay >	Arm7Overlays `[get]`
	Gets ARM7 overlays in table order.
NdsBanner?	Banner `[get]`
	Gets the parsed menu banner, or `null` when absent.
long	Length `[get]`
	Reports physical source bytes, which may exceed the header's used-ROM size because cartridges are capacity padded.

Detailed Description

Provides structured, random-access inspection of a Nintendo DS-family image.

Definition at line 4 of file NdsImage.cs.

Member Function Documentation

◆ CompareAsync()

ValueTask< NdsImageDiff > NdsForge.NdsImage.CompareAsync	(	NdsImage	other,
		CancellationToken	cancellationToken = default )

inline

Compares this image with another live image at semantic, numeric-identity, and physical-layout levels.

Parameters

other	Target image that remains caller-owned and live through hashing.
cancellationToken	Cancels either manifest capture.

Returns: A deterministic structured diff rather than console text or an undifferentiated byte offset.

Definition at line 207 of file NdsImage.cs.

◆ CopyToAsync()

async ValueTask NdsForge.NdsImage.CopyToAsync	(	NdsRegion	region,
		Stream	destination,
		CancellationToken	cancellationToken = default )

inline

Copies an arbitrary validated image interval without materializing it as one managed array.

Parameters

region	Half-open physical interval, commonly obtained from a typed component or allocation.
destination	Writable caller-owned stream positioned at the desired output location.
cancellationToken	Cancels bounded source reads and destination writes without closing either owner.

Returns: A task-like value that completes after the requested region has been copied.

Definition at line 110 of file NdsImage.cs.

◆ CreateManifestAsync()

ValueTask< NdsImageManifest > NdsForge.NdsImage.CreateManifestAsync ( CancellationToken cancellationToken = default )

inline

Captures a detached, SHA-256-addressed automation manifest without transferring image ownership.

Parameters

cancellationToken Cancels hashing of Programs, files, allocations, and the complete image.

Returns: A serialization-stable manifest containing no payload bytes.

Definition at line 197 of file NdsImage.cs.

◆ Dispose()

void NdsForge.NdsImage.Dispose ( )

inline

Synchronously releases the image source and prevents further payload access.

Definition at line 217 of file NdsImage.cs.

◆ DisposeAsync()

async ValueTask NdsForge.NdsImage.DisposeAsync ( )

inline

Asynchronously releases the image source and prevents further payload access.

Returns: A task-like value that completes after an asynchronously disposable source has been released.

Definition at line 230 of file NdsImage.cs.

◆ Edit()

NdsImageEditor NdsForge.NdsImage.Edit ( )

inline

Begins an explicit, non-mutating edit session for this source image.

Returns: A new editor with no pending changes.

Definition at line 177 of file NdsImage.cs.

◆ ExtractAsync()

ValueTask< NdsExtractionResult > NdsForge.NdsImage.ExtractAsync	(	string	destination,
		NdsExtractionOptions?	options = null,
		CancellationToken	cancellationToken = default )

inline

Safely exports selected image components to a directory.

Parameters

destination	The destination directory.
options	Optional component, filtering, and overwrite policies.
cancellationToken	A token used to cancel extraction.

Returns: A summary of files and bytes written.

Definition at line 164 of file NdsImage.cs.

◆ Load()

NdsImage NdsForge.NdsImage.Load	(	ReadOnlyMemory< byte >	data,
		NdsReadOptions?	options = null )

inlinestatic

Loads an image from caller-owned memory.

The memory must not be mutated while the returned image is in use.

Parameters

data	The complete image data.
options	Optional parser resource limits.

Returns: The loaded image. The caller must dispose it.

Definition at line 92 of file NdsImage.cs.

◆ Open()

NdsImage NdsForge.NdsImage.Open	(	Stream	stream,
		bool	leaveOpen = false,
		NdsReadOptions?	options = null )

inlinestatic

Opens an image from a caller-supplied readable, seekable stream.

Parameters

stream	The stream positioned anywhere; offset zero is treated as the image start.
leaveOpen	Whether disposing the image leaves the source stream open.
options	Optional parser resource limits.

Returns: The opened image. The caller must dispose it.

Definition at line 68 of file NdsImage.cs.

◆ OpenAsync() [1/2]

async ValueTask< NdsImage > NdsForge.NdsImage.OpenAsync	(	Stream	stream,
		bool	leaveOpen = false,
		NdsReadOptions?	options = null,
		CancellationToken	cancellationToken = default )

inlinestatic

Asynchronously opens an image from a caller-supplied readable, seekable stream.

Parameters

stream	The stream positioned anywhere; offset zero is treated as the image start.
leaveOpen	Whether disposing the image leaves the source stream open.
options	Optional parser resource limits.
cancellationToken	A token used to cancel parsing.

Returns: The opened image. The caller must dispose it.

Definition at line 80 of file NdsImage.cs.

◆ OpenAsync() [2/2]

async ValueTask< NdsImage > NdsForge.NdsImage.OpenAsync	(	string	path,
		NdsReadOptions?	options = null,
		CancellationToken	cancellationToken = default )

inlinestatic

Opens an image from a filesystem path without loading the entire file into memory.

Parameters

path	The image path.
options	Optional parser resource limits.
cancellationToken	A token used to cancel header reading.

Returns: The opened image. The caller must dispose it.

Definition at line 57 of file NdsImage.cs.

◆ OpenRead()

Stream NdsForge.NdsImage.OpenRead ( NdsRegion region )

inline

Opens a read-only stream over a validated image region.

Parameters

region The region to read.

Returns: A seekable stream bounded to the region.

Definition at line 98 of file NdsImage.cs.

◆ TransformModcryptAreaAsync()

async ValueTask NdsForge.NdsImage.TransformModcryptAreaAsync	(	NdsModcryptArea	area,
		Stream	destination,
		NdsModcryptContext	context,
		CancellationToken	cancellationToken = default )

inline

Reads one declared DSi modcrypt area and writes its symmetric AES-CTR transformation without loading the region into memory. The supplied context controls key provenance; neither caller-owned destination nor image is closed after completion.

Parameters

area	First or second extended-header interval.
destination	Writable stream positioned where transformed area bytes should begin.
context	Detached normal-key and HMAC-counter context.
cancellationToken	Cancels bounded image reads and destination writes.

Returns: A task-like value that completes after the complete declared area has been transformed.

Definition at line 136 of file NdsImage.cs.

◆ Validate()

NdsValidationResult NdsForge.NdsImage.Validate ( NdsValidationOptions? options = null )

inline

Validates checksums, component relationships, bounds, and optional DSi authentication fields.

Parameters

options Optional external trust material; keyless validation never guesses cryptographic provenance.

Returns: All detected diagnostics.

Definition at line 186 of file NdsImage.cs.

Property Documentation

◆ Arm7Overlays

IReadOnlyList<NdsOverlay> NdsForge.NdsImage.Arm7Overlays

get

Gets ARM7 overlays in table order.

Definition at line 44 of file NdsImage.cs.

◆ Arm9Overlays

IReadOnlyList<NdsOverlay> NdsForge.NdsImage.Arm9Overlays

get

Gets ARM9 overlays in table order.

Definition at line 41 of file NdsImage.cs.

◆ Banner

NdsBanner? NdsForge.NdsImage.Banner

get

Gets the parsed menu banner, or null when absent.

Definition at line 47 of file NdsImage.cs.

◆ FileSystem

NdsFileSystem NdsForge.NdsImage.FileSystem

get

Connects navigable FNT paths with every FAT allocation, including unnamed overlay payloads.

Definition at line 38 of file NdsImage.cs.

◆ Header

NdsHeader NdsForge.NdsImage.Header

get

Preserves both typed DS/DSi fields and the raw bytes required for checksums and lossless edits.

Definition at line 35 of file NdsImage.cs.

◆ Length

long NdsForge.NdsImage.Length

get

Reports physical source bytes, which may exceed the header's used-ROM size because cartridges are capacity padded.

Definition at line 50 of file NdsImage.cs.

The documentation for this class was generated from the following file:

src/NdsForge/NdsImage.cs

NdsForge.NET 1.0.1 Read, validate, edit, compare, and build Nintendo DS and DSi images from .NET

Public Member Functions

Static Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ CompareAsync()

◆ CopyToAsync()

◆ CreateManifestAsync()

◆ Dispose()

◆ DisposeAsync()

◆ Edit()

◆ ExtractAsync()

◆ Load()

◆ Open()

◆ OpenAsync() [1/2]

◆ OpenAsync() [2/2]

◆ OpenRead()

◆ TransformModcryptAreaAsync()

◆ Validate()

Property Documentation

◆ Arm7Overlays

◆ Arm9Overlays

◆ Banner

◆ FileSystem

◆ Header

◆ Length