Class MappedMemorySource

Namespace

CStructSharp.Memory

Assembly

CStructSharp.dll

An address space assembled from a table of mappings, each translating a logical range to a range of another source.

public sealed class MappedMemorySource : IMemoryMappingSource, IMemorySource

Inheritance

object

MappedMemorySource

Implements

IMemoryMappingSource

IMemorySource

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

This is the type that turns a scattered capture into something that looks like a process. A process sees consecutive pages; the capture stores them at arbitrary offsets, in one file or several. Each MemoryMapping records one placement, and this source answers a read by finding the mapping that contains the address, asking the backing source for as many bytes as that mapping can supply, and continuing with the next mapping until the request is complete. A read that crosses a boundary is therefore split and reassembled in logical order without the caller noticing.

The table is sorted once at construction so each lookup is a binary search. Logical ranges must not overlap, because an overlapping table would make translation ambiguous. Several logical ranges may point at the same backing bytes (aliasing, as when two processes share a library page); reads permit it, and MemoryPatch separately rejects overlapping physical fragments within one write plan. Backing regions may themselves belong to another mapped source, forming layers that MemoryPatch and Inspect(MemoryRegion, string, string, MemoryAccessContext?) flatten when they report physical coordinates.

Missing intervals are errors (Unmapped), never zero bytes. The source does not decode values, change byte order, discover hardware page tables, or take ownership of its backing sources.

Constructors

MappedMemorySource(string, IEnumerable<MemoryMapping>)

Snapshots and sorts the mapping table and rejects logical overlap.

public MappedMemorySource(string id, IEnumerable<MemoryMapping> mappings)

Parameters

id string

Diagnostic label; source objects, not labels, distinguish address spaces.

mappings IEnumerable<MemoryMapping>

Mappings with nonoverlapping logical ranges, copied at construction.

Properties

Generation

Gets a local counter that advances whenever any distinct backing source reports a changed generation.

public long Generation { get; }

Property Value

long

Remarks

The mapped source has no bytes of its own, so its generation is derived: each read of this property compares every backing source's current generation with the last one observed and bumps the local counter once per observed change. Backing generation numbers are compared, not summed, so unrelated snapshot labels cannot collide or overflow.

Id

Gets the diagnostic label for this source.

public string Id { get; }

Property Value

string

Methods

Describe(ulong, int, MemoryAccessContext?)

Translates one logical range into its backing fragments, in logical order, without reading any bytes.

public IReadOnlyList<MemoryRegion> Describe(ulong address, int length, MemoryAccessContext? context = null)

Parameters

address ulong

First logical address to translate.

length int

Number of logical bytes to translate.

context MemoryAccessContext

Shared operation budget and cancellation, or null to create a default budget.

Returns

IReadOnlyList<MemoryRegion>

Backing fragments covering the range, in logical order.

Remarks

This describes one mapping layer only. A returned fragment can itself belong to another mapped source; session inspection and patch planning follow those layers recursively. A hole anywhere in the range throws before a partial description is returned. Describing a range proves that the table covers it, not that a backing file will supply the bytes at read time.

Read(ulong, Span<byte>, MemoryAccessContext)

Copies up to destination.Length bytes starting at address and returns the count copied.

public int Read(ulong address, Span<byte> destination, MemoryAccessContext context)

Parameters

address ulong

Unsigned address in this source's own coordinate system (file offset, virtual address, or whatever the source defines).

destination Span<byte>

Caller-owned buffer, valid only for the duration of the call.

context MemoryAccessContext

Shared operation budget; leaf sources charge bytes, translation adapters charge zero-byte requests.

Returns

int

The number of bytes copied, never greater than the buffer length.

Remarks

Zero means the bytes are unavailable; a finite view turns that into a MissingBytes failure rather than treating it as end of file. An implementation may also throw a structured MemoryAccessException, for example Unmapped for a hole it can name.