diff --git a/src/LibHac/Fs/SubStorage.cs b/src/LibHac/Fs/SubStorage.cs index ff0103da..98421be4 100644 --- a/src/LibHac/Fs/SubStorage.cs +++ b/src/LibHac/Fs/SubStorage.cs @@ -3,6 +3,21 @@ using LibHac.Diag; namespace LibHac.Fs { + /// + /// Presents a subsection of a base IStorage as a new IStorage. + /// + /// + /// A SubStorage presents a sub-range of an IStorage as a separate IStorage. + /// + /// The SubStorage doesn't check if the offset and size provided are actually in the base storage. + /// GetSize will return the size given to the SubStorage at initialization and will not query + /// the base storage's size. + /// + /// A SubStorage is non-resizable by default. may be used to mark + /// the SubStorage as resizable. The SubStorage may only be resized if the end of the SubStorage + /// is located at the end of the base storage. When resizing the SubStorage, the base storage + /// will be resized to the appropriate length. + /// public class SubStorage : IStorage { private ReferenceCountedDisposable SharedBaseStorage { get; set; } @@ -11,6 +26,9 @@ namespace LibHac.Fs private long Size { get; set; } private bool IsResizable { get; set; } + /// + /// Creates an uninitialized . It must be initialized with before using. + /// public SubStorage() { BaseStorage = null; @@ -19,6 +37,11 @@ namespace LibHac.Fs IsResizable = false; } + /// + /// Creates a copy of . + /// will not be disposed when the created is disposed. + /// + /// The to create a copy of. Caller retains ownership. public SubStorage(SubStorage other) { BaseStorage = other.BaseStorage; @@ -27,10 +50,16 @@ namespace LibHac.Fs IsResizable = other.IsResizable; } + /// + /// Initializes or reinitializes this as a copy of . + /// Any shared references in will be copied. + /// + /// The used to initialize this one. public void InitializeFrom(SubStorage other) { if (this != other) { + SharedBaseStorage = other.SharedBaseStorage.AddReference(); BaseStorage = other.BaseStorage; Offset = other.Offset; Size = other.Size; @@ -38,6 +67,13 @@ namespace LibHac.Fs } } + /// + /// Creates a from a subsection of another . + /// will not be disposed when the created is disposed. + /// + /// The base . Caller retains ownership. + /// The offset in the base storage at which to begin the created SubStorage. + /// The size of the SubStorage. public SubStorage(IStorage baseStorage, long offset, long size) { BaseStorage = baseStorage; @@ -50,6 +86,13 @@ namespace LibHac.Fs Assert.AssertTrue(Size >= 0); } + /// + /// Creates a from a subsection of another . + /// Holds a reference to until disposed. + /// + /// The base IStorage. + /// The offset in the base storage at which to begin the created SubStorage. + /// The size of the SubStorage. public SubStorage(ReferenceCountedDisposable sharedBaseStorage, long offset, long size) { SharedBaseStorage = sharedBaseStorage.AddReference(); @@ -63,21 +106,38 @@ namespace LibHac.Fs Assert.AssertTrue(Size >= 0); } - public SubStorage(SubStorage subStorage, long offset, long size) + /// + /// Creates a from a subsection of another . + /// will not be disposed when the created is disposed. + /// + /// + /// The created SubStorage will directly use the base SubStorage of and will + /// adjust the and accordingly. + /// This avoids the overhead of going through two SubStorage layers. + /// + /// The base SubStorage. + /// The offset in the base storage at which to begin the created SubStorage. + /// The size of the SubStorage. + public SubStorage(SubStorage other, long offset, long size) { - BaseStorage = subStorage.BaseStorage; - Offset = subStorage.Offset + offset; + BaseStorage = other.BaseStorage; + Offset = other.Offset + offset; Size = size; IsResizable = false; Assert.AssertTrue(IsValid()); Assert.AssertTrue(Offset >= 0); Assert.AssertTrue(Size >= 0); - Assert.AssertTrue(subStorage.Size >= offset + size); + Assert.AssertTrue(other.Size >= offset + size); } private bool IsValid() => BaseStorage != null; + /// + /// Sets whether the is resizable or not. + /// + /// if the should + /// be resizable. if not. public void SetResizable(bool isResizable) { IsResizable = isResizable; diff --git a/src/LibHac/FsSystem/TruncatedSubStorage.cs b/src/LibHac/FsSystem/TruncatedSubStorage.cs index fcb25b1c..836c5db7 100644 --- a/src/LibHac/FsSystem/TruncatedSubStorage.cs +++ b/src/LibHac/FsSystem/TruncatedSubStorage.cs @@ -3,6 +3,14 @@ using LibHac.Fs; namespace LibHac.FsSystem { + /// + /// A that truncates reads and writes that extend past the end of the base storage. + /// + /// + /// When reading and writing from a , the size of the base + /// storage will be checked. If needed, the size of the requested read/write will be truncated + /// to stay within the bounds of the base storage. + /// public class TruncatedSubStorage : SubStorage { public TruncatedSubStorage() { }