diff --git a/src/LibHac/Fs/Fsa/IDirectory2.cs b/src/LibHac/Fs/Fsa/IDirectory2.cs index 064279df..cfa58a9a 100644 --- a/src/LibHac/Fs/Fsa/IDirectory2.cs +++ b/src/LibHac/Fs/Fsa/IDirectory2.cs @@ -3,8 +3,23 @@ namespace LibHac.Fs.Fsa { // ReSharper disable once InconsistentNaming + /// + /// Provides an interface for enumerating the child entries of a directory. + /// public abstract class IDirectory2 : IDisposable { + /// + /// Retrieves the next entries that this directory contains. Does not search subdirectories. + /// + /// The number of s that + /// were read into . + /// The buffer the entries will be read into. + /// The of the requested operation. + /// With each call of , the object will + /// continue to iterate through all the entries it contains. + /// Each call will attempt to read as many entries as the buffer can contain. + /// Once all the entries have been read, all subsequent calls to will + /// read 0 entries into the buffer. public Result Read(out long entriesRead, Span entryBuffer) { if (entryBuffer.IsEmpty) @@ -16,6 +31,11 @@ namespace LibHac.Fs.Fsa return DoRead(out entriesRead, entryBuffer); } + /// + /// Retrieves the number of file system entries that this directory contains. Does not search subdirectories. + /// + /// The number of child entries the directory contains. + /// The of the requested operation. public Result GetEntryCount(out long entryCount) { return DoGetEntryCount(out entryCount); diff --git a/src/LibHac/Fs/Fsa/IFile2.cs b/src/LibHac/Fs/Fsa/IFile2.cs index d0251f1a..8c075d00 100644 --- a/src/LibHac/Fs/Fsa/IFile2.cs +++ b/src/LibHac/Fs/Fsa/IFile2.cs @@ -4,8 +4,32 @@ using LibHac.Diag; namespace LibHac.Fs.Fsa { // ReSharper disable once InconsistentNaming + /// + /// Provides an interface for reading and writing a sequence of bytes. + /// + /// is similar to , and has a few main differences: + /// + /// - allows an to be set that controls read, write + /// and append permissions for the file. + /// + /// - If the cannot read or write as many bytes as requested, it will read + /// or write as many bytes as it can and return that number of bytes to the caller. + /// + /// - If is called on an offset past the end of the , + /// the mode is set and the file supports expansion, + /// the file will be expanded so that it is large enough to contain the written data. public abstract class IFile2 : IDisposable { + /// + /// Reads a sequence of bytes from the current . + /// + /// If the operation returns successfully, The total number of bytes read into + /// the buffer. This can be less than the size of the buffer if the IFile is too short to fulfill the request. + /// The offset in the at which to begin reading. + /// The buffer where the read bytes will be stored. + /// The number of bytes read will be no larger than the length of the buffer. + /// Options for reading from the . + /// The of the requested operation. public Result Read(out long bytesRead, long offset, Span destination, in ReadOption option) { if (destination.IsEmpty) @@ -29,11 +53,27 @@ namespace LibHac.Fs.Fsa return DoRead(out bytesRead, offset, destination, in option); } + /// + /// Reads a sequence of bytes from the current with no s. + /// + /// If the operation returns successfully, The total number of bytes read into + /// the buffer. This can be less than the size of the buffer if the IFile is too short to fulfill the request. + /// The offset in the at which to begin reading. + /// The buffer where the read bytes will be stored. + /// The number of bytes read will be no larger than the length of the buffer. + /// The of the requested operation. public Result Read(out long bytesRead, long offset, Span destination) { return Read(out bytesRead, offset, destination, ReadOption.None); } + /// + /// Writes a sequence of bytes to the current . + /// + /// The offset in the at which to begin writing. + /// The buffer containing the bytes to be written. + /// Options for writing to the . + /// The of the requested operation. public Result Write(long offset, ReadOnlySpan source, in WriteOption option) { if (source.IsEmpty) @@ -56,11 +96,19 @@ namespace LibHac.Fs.Fsa return DoWrite(offset, source, in option); } + /// + /// Causes any buffered data to be written to the underlying device. + /// public Result Flush() { return DoFlush(); } + /// + /// Sets the size of the file in bytes. + /// + /// The desired size of the file in bytes. + /// The of the requested operation. public Result SetSize(long size) { if (size < 0) @@ -69,17 +117,38 @@ namespace LibHac.Fs.Fsa return DoSetSize(size); } + /// + /// Gets the number of bytes in the file. + /// + /// If the operation returns successfully, the length of the file in bytes. + /// The of the requested operation. public Result GetSize(out long size) { return DoGetSize(out size); } + /// + /// Performs various operations on the file. Used to extend the functionality of the interface. + /// + /// A buffer that will contain the response from the operation. + /// The operation to be performed. + /// The offset of the range to operate on. + /// The size of the range to operate on. + /// An input buffer. Size may vary depending on the operation performed. + /// The of the requested operation. public Result OperateRange(Span outBuffer, OperationId operationId, long offset, long size, ReadOnlySpan inBuffer) { return DoOperateRange(outBuffer, operationId, offset, size, inBuffer); } + /// + /// Performs various operations on the file. Used to extend the functionality of the interface. + /// + /// The operation to be performed. + /// The offset of the range to operate on. + /// The size of the range to operate on. + /// The of the requested operation. public Result OperateRange(OperationId operationId, long offset, long size) { return DoOperateRange(Span.Empty, operationId, offset, size, ReadOnlySpan.Empty); diff --git a/src/LibHac/Fs/Fsa/IFileSystem2.cs b/src/LibHac/Fs/Fsa/IFileSystem2.cs index 2d1ff525..65c3caaf 100644 --- a/src/LibHac/Fs/Fsa/IFileSystem2.cs +++ b/src/LibHac/Fs/Fsa/IFileSystem2.cs @@ -4,8 +4,26 @@ using LibHac.Common; namespace LibHac.Fs.Fsa { // ReSharper disable once InconsistentNaming + /// + /// Provides an interface for accessing a file system. / is used as the path delimiter. + /// public abstract class IFileSystem2 : IDisposable { + /// + /// Creates or overwrites a file at the specified path. + /// + /// The full path of the file to create. + /// The initial size of the created file. + /// Flags to control how the file is created. + /// Should usually be + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The parent directory of the specified path does not exist: + /// Specified path already exists as either a file or directory: + /// Insufficient free space to create the file: + /// public Result CreateFile(U8Span path, long size, CreateFileOptions option) { if (path.IsNull()) @@ -17,6 +35,16 @@ namespace LibHac.Fs.Fsa return DoCreateFile(path, size, option); } + /// + /// Deletes the specified file. + /// + /// The full path of the file to delete. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a directory: + /// public Result DeleteFile(U8Span path) { if (path.IsNull()) @@ -25,6 +53,18 @@ namespace LibHac.Fs.Fsa return DoDeleteFile(path); } + /// + /// Creates all directories and subdirectories in the specified path unless they already exist. + /// + /// The full path of the directory to create. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The parent directory of the specified path does not exist: + /// Specified path already exists as either a file or directory: + /// Insufficient free space to create the directory: + /// public Result CreateDirectory(U8Span path) { if (path.IsNull()) @@ -33,6 +73,17 @@ namespace LibHac.Fs.Fsa return DoCreateDirectory(path); } + /// + /// Deletes the specified directory. + /// + /// The full path of the directory to delete. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a file: + /// The specified directory is not empty: + /// public Result DeleteDirectory(U8Span path) { if (path.IsNull()) @@ -41,6 +92,16 @@ namespace LibHac.Fs.Fsa return DoDeleteDirectory(path); } + /// + /// Deletes the specified directory and any subdirectories and files in the directory. + /// + /// The full path of the directory to delete. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a file: + /// public Result DeleteDirectoryRecursively(U8Span path) { if (path.IsNull()) @@ -49,6 +110,16 @@ namespace LibHac.Fs.Fsa return DoDeleteDirectoryRecursively(path); } + /// + /// Deletes any subdirectories and files in the specified directory. + /// + /// The full path of the directory to clean. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a file: + /// public Result CleanDirectoryRecursively(U8Span path) { if (path.IsNull()) @@ -57,6 +128,20 @@ namespace LibHac.Fs.Fsa return DoCleanDirectoryRecursively(path); } + /// + /// Renames or moves a file to a new location. + /// + /// The full path of the file to rename. + /// The new full path of the file. + /// The of the requested operation. + /// + /// If and are the same, this function does nothing and returns successfully. + /// The following codes may be returned under certain conditions: + /// + /// does not exist or is a directory: + /// 's parent directory does not exist: + /// already exists as either a file or directory: + /// public Result RenameFile(U8Span oldPath, U8Span newPath) { if (oldPath.IsNull()) @@ -68,6 +153,21 @@ namespace LibHac.Fs.Fsa return DoRenameFile(oldPath, newPath); } + /// + /// Renames or moves a directory to a new location. + /// + /// The full path of the directory to rename. + /// The new full path of the directory. + /// The of the requested operation. + /// + /// If and are the same, this function does nothing and returns . + /// The following codes may be returned under certain conditions: + /// + /// does not exist or is a file: + /// 's parent directory does not exist: + /// already exists as either a file or directory: + /// Either or is a subpath of the other: + /// public Result RenameDirectory(U8Span oldPath, U8Span newPath) { if (oldPath.IsNull()) @@ -79,6 +179,12 @@ namespace LibHac.Fs.Fsa return DoRenameDirectory(oldPath, newPath); } + /// + /// Determines whether the specified path is a file or directory, or does not exist. + /// + /// If the operation returns successfully, the of the file. + /// The full path to check. + /// The of the requested operation. public Result GetEntryType(out DirectoryEntryType entryType, U8Span path) { if (path.IsNull()) @@ -90,6 +196,12 @@ namespace LibHac.Fs.Fsa return DoGetEntryType(out entryType, path); } + /// + /// Gets the amount of available free space on a drive, in bytes. + /// + /// If the operation returns successfully, the amount of free space available on the drive, in bytes. + /// The path of the drive to query. Unused in almost all cases. + /// The of the requested operation. public Result GetFreeSpaceSize(out long freeSpace, U8Span path) { if (path.IsNull()) @@ -101,6 +213,12 @@ namespace LibHac.Fs.Fsa return DoGetFreeSpaceSize(out freeSpace, path); } + /// + /// Gets the total size of storage space on a drive, in bytes. + /// + /// If the operation returns successfully, the total size of the drive, in bytes. + /// The path of the drive to query. Unused in almost all cases. + /// The of the requested operation. public Result GetTotalSpaceSize(out long totalSpace, U8Span path) { if (path.IsNull()) @@ -112,6 +230,19 @@ namespace LibHac.Fs.Fsa return DoGetTotalSpaceSize(out totalSpace, path); } + /// + /// Opens an instance for the specified path. + /// + /// If the operation returns successfully, + /// An instance for the specified path. + /// The full path of the file to open. + /// Specifies the access permissions of the created . + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a directory: + /// public Result OpenFile(out IFile2 file, U8Span path, OpenMode mode) { if (path.IsNull()) @@ -135,6 +266,19 @@ namespace LibHac.Fs.Fsa return DoOpenFile(out file, path, mode); } + /// + /// Creates an instance for enumerating the specified directory. + /// + /// If the operation returns successfully, + /// An instance for the specified directory. + /// The directory's full path. + /// Specifies which sub-entries should be enumerated. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist or is a file: + /// public Result OpenDirectory(out IDirectory2 directory, U8Span path, OpenDirectoryMode mode) { if (path.IsNull()) @@ -158,6 +302,11 @@ namespace LibHac.Fs.Fsa return DoOpenDirectory(out directory, path, mode); } + /// + /// Commits any changes to a transactional file system. + /// Does nothing if called on a non-transactional file system. + /// + /// The of the requested operation. public Result Commit() => DoCommit(); public Result CommitProvisionally(long counter) => DoCommitProvisionally(counter); @@ -166,6 +315,18 @@ namespace LibHac.Fs.Fsa public Result Flush() => DoFlush(); + /// + /// Gets the creation, last accessed, and last modified timestamps of a file or directory. + /// + /// If the operation returns successfully, the timestamps for the specified file or directory. + /// These value are expressed as Unix timestamps. + /// The path of the file or directory. + /// The of the requested operation. + /// + /// The following codes may be returned under certain conditions: + /// + /// The specified path does not exist: + /// public Result GetFileTimeStampRaw(out FileTimeStampRaw timeStamp, U8Span path) { if (path.IsNull()) @@ -177,6 +338,18 @@ namespace LibHac.Fs.Fsa return DoGetFileTimeStampRaw(out timeStamp, path); } + /// + /// Performs a query on the specified file. + /// + /// This method allows implementers of to accept queries and operations + /// not included in the IFileSystem interface itself. + /// The buffer for receiving data from the query operation. + /// May be unused depending on the query type. + /// The buffer for sending data to the query operation. + /// May be unused depending on the query type. + /// The type of query to perform. + /// The full path of the file to query. + /// The of the requested operation. public Result QueryEntry(Span outBuffer, ReadOnlySpan inBuffer, QueryId queryId, U8Span path) { if (path.IsNull())