mirrors/LibHac
1
0
Fork 0
mirror of https://github.com/Thealexbarney/LibHac.git synced 2024-11-14 10:49:41 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add XML docs

Browse source
This commit is contained in:
Alex Barney 2020-06-07 00:05:33 -07:00
parent 7c9584a6af
commit ba1bf2f1c8
3 changed files with 262 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
src/LibHac/Fs/Fsa/IDirectory2.cs
View file

@ -3,8 +3,23 @@
namespace LibHac.Fs.Fsa
{
// ReSharper disable once InconsistentNaming
/// <summary>
/// Provides an interface for enumerating the child entries of a directory.
/// </summary>
public abstract class IDirectory2 : IDisposable
{
/// <summary>
/// Retrieves the next entries that this directory contains. Does not search subdirectories.
/// </summary>
/// <param name="entriesRead">The number of <see cref="DirectoryEntry"/>s that
/// were read into <paramref name="entryBuffer"/>.</param>
/// <param name="entryBuffer">The buffer the entries will be read into.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>With each call of <see cref="Read"/>, the <see cref="IDirectory2"/> 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 <see cref="Read"/> will
/// read 0 entries into the buffer.</remarks>
public Result Read(out long entriesRead, Span<DirectoryEntry> entryBuffer)
{
if (entryBuffer.IsEmpty)
@ -16,6 +31,11 @@ namespace LibHac.Fs.Fsa
return DoRead(out entriesRead, entryBuffer);
}
/// <summary>
/// Retrieves the number of file system entries that this directory contains. Does not search subdirectories.
/// </summary>
/// <param name="entryCount">The number of child entries the directory contains.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result GetEntryCount(out long entryCount)
{
return DoGetEntryCount(out entryCount);

69
src/LibHac/Fs/Fsa/IFile2.cs
View file

@ -4,8 +4,32 @@ using LibHac.Diag;
namespace LibHac.Fs.Fsa
{
// ReSharper disable once InconsistentNaming
/// <summary>
/// Provides an interface for reading and writing a sequence of bytes.
/// </summary>
/// <remarks><see cref="IFile"/> is similar to <see cref="IStorage"/>, and has a few main differences:
///
/// - <see cref="IFile"/> allows an <see cref="OpenMode"/> to be set that controls read, write
/// and append permissions for the file.
///
/// - If the <see cref="IFile"/> 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 <see cref="Write"/> is called on an offset past the end of the <see cref="IFile"/>,
/// the <see cref="OpenMode.AllowAppend"/> mode is set and the file supports expansion,
/// the file will be expanded so that it is large enough to contain the written data.</remarks>
public abstract class IFile2 : IDisposable
{
/// <summary>
/// Reads a sequence of bytes from the current <see cref="IFile"/>.
/// </summary>
/// <param name="bytesRead">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.</param>
/// <param name="offset">The offset in the <see cref="IFile"/> at which to begin reading.</param>
/// <param name="destination">The buffer where the read bytes will be stored.
/// The number of bytes read will be no larger than the length of the buffer.</param>
/// <param name="option">Options for reading from the <see cref="IFile"/>.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result Read(out long bytesRead, long offset, Span<byte> destination, in ReadOption option)
{
if (destination.IsEmpty)
@ -29,11 +53,27 @@ namespace LibHac.Fs.Fsa
return DoRead(out bytesRead, offset, destination, in option);
}
/// <summary>
/// Reads a sequence of bytes from the current <see cref="IFile"/> with no <see cref="ReadOption"/>s.
/// </summary>
/// <param name="bytesRead">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.</param>
/// <param name="offset">The offset in the <see cref="IFile"/> at which to begin reading.</param>
/// <param name="destination">The buffer where the read bytes will be stored.
/// The number of bytes read will be no larger than the length of the buffer.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result Read(out long bytesRead, long offset, Span<byte> destination)
{
return Read(out bytesRead, offset, destination, ReadOption.None);
}
/// <summary>
/// Writes a sequence of bytes to the current <see cref="IFile"/>.
/// </summary>
/// <param name="offset">The offset in the <see cref="IStorage"/> at which to begin writing.</param>
/// <param name="source">The buffer containing the bytes to be written.</param>
/// <param name="option">Options for writing to the <see cref="IFile"/>.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result Write(long offset, ReadOnlySpan<byte> source, in WriteOption option)
{
if (source.IsEmpty)
@ -56,11 +96,19 @@ namespace LibHac.Fs.Fsa
return DoWrite(offset, source, in option);
}
/// <summary>
/// Causes any buffered data to be written to the underlying device.
/// </summary>
public Result Flush()
{
return DoFlush();
}
/// <summary>
/// Sets the size of the file in bytes.
/// </summary>
/// <param name="size">The desired size of the file in bytes.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result SetSize(long size)
{
if (size < 0)
@ -69,17 +117,38 @@ namespace LibHac.Fs.Fsa
return DoSetSize(size);
}
/// <summary>
/// Gets the number of bytes in the file.
/// </summary>
/// <param name="size">If the operation returns successfully, the length of the file in bytes.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result GetSize(out long size)
{
return DoGetSize(out size);
}
/// <summary>
/// Performs various operations on the file. Used to extend the functionality of the <see cref="IFile"/> interface.
/// </summary>
/// <param name="outBuffer">A buffer that will contain the response from the operation.</param>
/// <param name="operationId">The operation to be performed.</param>
/// <param name="offset">The offset of the range to operate on.</param>
/// <param name="size">The size of the range to operate on.</param>
/// <param name="inBuffer">An input buffer. Size may vary depending on the operation performed.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result OperateRange(Span<byte> outBuffer, OperationId operationId, long offset, long size,
ReadOnlySpan<byte> inBuffer)
{
return DoOperateRange(outBuffer, operationId, offset, size, inBuffer);
}
/// <summary>
/// Performs various operations on the file. Used to extend the functionality of the <see cref="IFile"/> interface.
/// </summary>
/// <param name="operationId">The operation to be performed.</param>
/// <param name="offset">The offset of the range to operate on.</param>
/// <param name="size">The size of the range to operate on.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result OperateRange(OperationId operationId, long offset, long size)
{
return DoOperateRange(Span<byte>.Empty, operationId, offset, size, ReadOnlySpan<byte>.Empty);

173
src/LibHac/Fs/Fsa/IFileSystem2.cs
View file

@ -4,8 +4,26 @@ using LibHac.Common;
namespace LibHac.Fs.Fsa
{
// ReSharper disable once InconsistentNaming
/// <summary>
/// Provides an interface for accessing a file system. <c>/</c> is used as the path delimiter.
/// </summary>
public abstract class IFileSystem2 : IDisposable
{
/// <summary>
/// Creates or overwrites a file at the specified path.
/// </summary>
/// <param name="path">The full path of the file to create.</param>
/// <param name="size">The initial size of the created file.</param>
/// <param name="option">Flags to control how the file is created.
/// Should usually be <see cref="CreateFileOptions.None"/></param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The parent directory of the specified path does not exist: <see cref="ResultFs.PathNotFound"/>
/// Specified path already exists as either a file or directory: <see cref="ResultFs.PathAlreadyExists"/>
/// Insufficient free space to create the file: <see cref="ResultFs.InsufficientFreeSpace"/>
/// </remarks>
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);
}
/// <summary>
/// Deletes the specified file.
/// </summary>
/// <param name="path">The full path of the file to delete.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a directory: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
public Result DeleteFile(U8Span path)
{
if (path.IsNull())
@ -25,6 +53,18 @@ namespace LibHac.Fs.Fsa
return DoDeleteFile(path);
}
/// <summary>
/// Creates all directories and subdirectories in the specified path unless they already exist.
/// </summary>
/// <param name="path">The full path of the directory to create.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The parent directory of the specified path does not exist: <see cref="ResultFs.PathNotFound"/>
/// Specified path already exists as either a file or directory: <see cref="ResultFs.PathAlreadyExists"/>
/// Insufficient free space to create the directory: <see cref="ResultFs.InsufficientFreeSpace"/>
/// </remarks>
public Result CreateDirectory(U8Span path)
{
if (path.IsNull())
@ -33,6 +73,17 @@ namespace LibHac.Fs.Fsa
return DoCreateDirectory(path);
}
/// <summary>
/// Deletes the specified directory.
/// </summary>
/// <param name="path">The full path of the directory to delete.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a file: <see cref="ResultFs.PathNotFound"/>
/// The specified directory is not empty: <see cref="ResultFs.DirectoryNotEmpty"/>
/// </remarks>
public Result DeleteDirectory(U8Span path)
{
if (path.IsNull())
@ -41,6 +92,16 @@ namespace LibHac.Fs.Fsa
return DoDeleteDirectory(path);
}
/// <summary>
/// Deletes the specified directory and any subdirectories and files in the directory.
/// </summary>
/// <param name="path">The full path of the directory to delete.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a file: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
public Result DeleteDirectoryRecursively(U8Span path)
{
if (path.IsNull())
@ -49,6 +110,16 @@ namespace LibHac.Fs.Fsa
return DoDeleteDirectoryRecursively(path);
}
/// <summary>
/// Deletes any subdirectories and files in the specified directory.
/// </summary>
/// <param name="path">The full path of the directory to clean.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a file: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
public Result CleanDirectoryRecursively(U8Span path)
{
if (path.IsNull())
@ -57,6 +128,20 @@ namespace LibHac.Fs.Fsa
return DoCleanDirectoryRecursively(path);
}
/// <summary>
/// Renames or moves a file to a new location.
/// </summary>
/// <param name="oldPath">The full path of the file to rename.</param>
/// <param name="newPath">The new full path of the file.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// If <paramref name="oldPath"/> and <paramref name="newPath"/> are the same, this function does nothing and returns successfully.
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// <paramref name="oldPath"/> does not exist or is a directory: <see cref="ResultFs.PathNotFound"/>
/// <paramref name="newPath"/>'s parent directory does not exist: <see cref="ResultFs.PathNotFound"/>
/// <paramref name="newPath"/> already exists as either a file or directory: <see cref="ResultFs.PathAlreadyExists"/>
/// </remarks>
public Result RenameFile(U8Span oldPath, U8Span newPath)
{
if (oldPath.IsNull())
@ -68,6 +153,21 @@ namespace LibHac.Fs.Fsa
return DoRenameFile(oldPath, newPath);
}
/// <summary>
/// Renames or moves a directory to a new location.
/// </summary>
/// <param name="oldPath">The full path of the directory to rename.</param>
/// <param name="newPath">The new full path of the directory.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// If <paramref name="oldPath"/> and <paramref name="newPath"/> are the same, this function does nothing and returns <see cref="Result.Success"/>.
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// <paramref name="oldPath"/> does not exist or is a file: <see cref="ResultFs.PathNotFound"/>
/// <paramref name="newPath"/>'s parent directory does not exist: <see cref="ResultFs.PathNotFound"/>
/// <paramref name="newPath"/> already exists as either a file or directory: <see cref="ResultFs.PathAlreadyExists"/>
/// Either <paramref name="oldPath"/> or <paramref name="newPath"/> is a subpath of the other: <see cref="ResultFs.DestinationIsSubPathOfSource"/>
/// </remarks>
public Result RenameDirectory(U8Span oldPath, U8Span newPath)
{
if (oldPath.IsNull())
@ -79,6 +179,12 @@ namespace LibHac.Fs.Fsa
return DoRenameDirectory(oldPath, newPath);
}
/// <summary>
/// Determines whether the specified path is a file or directory, or does not exist.
/// </summary>
/// <param name="entryType">If the operation returns successfully, the <see cref="DirectoryEntryType"/> of the file.</param>
/// <param name="path">The full path to check.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result GetEntryType(out DirectoryEntryType entryType, U8Span path)
{
if (path.IsNull())
@ -90,6 +196,12 @@ namespace LibHac.Fs.Fsa
return DoGetEntryType(out entryType, path);
}
/// <summary>
/// Gets the amount of available free space on a drive, in bytes.
/// </summary>
/// <param name="freeSpace">If the operation returns successfully, the amount of free space available on the drive, in bytes.</param>
/// <param name="path">The path of the drive to query. Unused in almost all cases.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result GetFreeSpaceSize(out long freeSpace, U8Span path)
{
if (path.IsNull())
@ -101,6 +213,12 @@ namespace LibHac.Fs.Fsa
return DoGetFreeSpaceSize(out freeSpace, path);
}
/// <summary>
/// Gets the total size of storage space on a drive, in bytes.
/// </summary>
/// <param name="totalSpace">If the operation returns successfully, the total size of the drive, in bytes.</param>
/// <param name="path">The path of the drive to query. Unused in almost all cases.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result GetTotalSpaceSize(out long totalSpace, U8Span path)
{
if (path.IsNull())
@ -112,6 +230,19 @@ namespace LibHac.Fs.Fsa
return DoGetTotalSpaceSize(out totalSpace, path);
}
/// <summary>
/// Opens an <see cref="IFile"/> instance for the specified path.
/// </summary>
/// <param name="file">If the operation returns successfully,
/// An <see cref="IFile"/> instance for the specified path.</param>
/// <param name="path">The full path of the file to open.</param>
/// <param name="mode">Specifies the access permissions of the created <see cref="IFile"/>.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a directory: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
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);
}
/// <summary>
/// Creates an <see cref="IDirectory"/> instance for enumerating the specified directory.
/// </summary>
/// <param name="directory">If the operation returns successfully,
/// An <see cref="IDirectory"/> instance for the specified directory.</param>
/// <param name="path">The directory's full path.</param>
/// <param name="mode">Specifies which sub-entries should be enumerated.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist or is a file: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
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);
}
/// <summary>
/// Commits any changes to a transactional file system.
/// Does nothing if called on a non-transactional file system.
/// </summary>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result Commit() => DoCommit();
public Result CommitProvisionally(long counter) => DoCommitProvisionally(counter);
@ -166,6 +315,18 @@ namespace LibHac.Fs.Fsa
public Result Flush() => DoFlush();
/// <summary>
/// Gets the creation, last accessed, and last modified timestamps of a file or directory.
/// </summary>
/// <param name="timeStamp">If the operation returns successfully, the timestamps for the specified file or directory.
/// These value are expressed as Unix timestamps.</param>
/// <param name="path">The path of the file or directory.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
/// <remarks>
/// The following <see cref="Result"/> codes may be returned under certain conditions:
///
/// The specified path does not exist: <see cref="ResultFs.PathNotFound"/>
/// </remarks>
public Result GetFileTimeStampRaw(out FileTimeStampRaw timeStamp, U8Span path)
{
if (path.IsNull())
@ -177,6 +338,18 @@ namespace LibHac.Fs.Fsa
return DoGetFileTimeStampRaw(out timeStamp, path);
}
/// <summary>
/// Performs a query on the specified file.
/// </summary>
/// <remarks>This method allows implementers of <see cref="IFileSystem"/> to accept queries and operations
/// not included in the IFileSystem interface itself.</remarks>
/// <param name="outBuffer">The buffer for receiving data from the query operation.
/// May be unused depending on the query type.</param>
/// <param name="inBuffer">The buffer for sending data to the query operation.
/// May be unused depending on the query type.</param>
/// <param name="queryId">The type of query to perform.</param>
/// <param name="path">The full path of the file to query.</param>
/// <returns>The <see cref="Result"/> of the requested operation.</returns>
public Result QueryEntry(Span<byte> outBuffer, ReadOnlySpan<byte> inBuffer, QueryId queryId, U8Span path)
{
if (path.IsNull())