Public/winfsp
1
0
Fork 0
mirror of https://github.com/winfsp/winfsp.git synced 2025-04-22 08:23:05 -05:00
Code Issues Packages Projects Releases Wiki Activity

src: dotnet: add documentation

Browse Source
This commit is contained in:
Bill Zissimopoulos 2017-05-10 23:11:42 -07:00
parent 2560a513dc
commit 7cd4d4faab
6 changed files with 831 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
build/VStudio/dotnet/winfsp.net.csproj
View File

@ -25,6 +25,8 @@
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
<DocumentationFile>$(BaseIntermediateOutputPath)$(Configuration)\winfsp-msil.xml</DocumentationFile>
<NoWarn>1591</NoWarn>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
@ -36,6 +38,8 @@
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
<DocumentationFile>$(BaseIntermediateOutputPath)$(Configuration)\winfsp-msil.xml</DocumentationFile>
<NoWarn>1591</NoWarn>
</PropertyGroup>
<PropertyGroup>
<SignAssembly>true</SignAssembly>

6
src/dotnet/FileSystemBase+Const.cs
View File

@ -1,7 +1,7 @@
/**
* @file dotnet/FileSystemBase+Const.cs
/*
* dotnet/FileSystemBase+Const.cs
*
* @copyright 2015-2017 Bill Zissimopoulos
* Copyright 2015-2017 Bill Zissimopoulos
*/
/*
* This file is part of WinFsp.

635
src/dotnet/FileSystemBase.cs
View File

@ -1,7 +1,7 @@
/**
* @file dotnet/FileSystemBase.cs
/*
* dotnet/FileSystemBase.cs
*
* @copyright 2015-2017 Bill Zissimopoulos
* Copyright 2015-2017 Bill Zissimopoulos
*/
/*
* This file is part of WinFsp.
@ -24,6 +24,9 @@ using Fsp.Interop;
namespace Fsp
{
/// <summary>
/// Provides the base class that user mode file systems must inherit from.
/// </summary>
public partial class FileSystemBase
{
/* types */
@ -48,28 +51,61 @@ namespace Fsp
}
/* operations */
/// <summary>
/// Provides a means to customize the returned status code when an exception happens.
/// </summary>
/// <param name="ex"></param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 ExceptionHandler(Exception ex)
{
Api.FspDebugLog("%s\n", ex.ToString());
return STATUS_UNEXPECTED_IO_ERROR;
}
/// <summary>
/// Occurs just before the file system is mounted.
/// File systems may override this method to configure the file system host.
/// </summary>
/// <param name="Host">The file system host that is mounting this file system.</param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Init(Object Host)
{
return STATUS_SUCCESS;
}
/// <summary>
/// Occurs just after the file system is mounted,
/// but prior to receiving any file system operation.
/// </summary>
/// <param name="Host">The file system host that is mounting this file system.</param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Mounted(Object Host)
{
return STATUS_SUCCESS;
}
/// <summary>
/// Occurs just after the file system is unmounted.
/// No other file system operations will be received on this file system.
/// </summary>
/// <param name="Host">The file system host that is mounting this file system.</param>
public virtual void Unmounted(Object Host)
{
}
/// <summary>
/// Gets the volume information.
/// </summary>
/// <param name="VolumeInfo">Receives the volume information.</param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 GetVolumeInfo(
out VolumeInfo VolumeInfo)
{
VolumeInfo = default(VolumeInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Sets the volume label.
/// </summary>
/// <param name="VolumeLabel">The new label for the volume.</param>
/// <param name="VolumeInfo">Receives the updated volume information.</param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 SetVolumeLabel(
String VolumeLabel,
out VolumeInfo VolumeInfo)
@ -77,6 +113,27 @@ namespace Fsp
VolumeInfo = default(VolumeInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Gets file or directory attributes and security descriptor given a file name.
/// </summary>
/// <param name="FileName">
/// The name of the file or directory to get the attributes and security descriptor for.
/// </param>
/// <param name="FileAttributes">
/// Receives the file attributes on successful return.
/// If this call returns STATUS_REPARSE, the file system may place here the index of the
/// first reparse point within FileName.
/// </param>
/// <param name="SecurityDescriptor">
/// Receives the file security descriptor. If the SecurityDescriptor parameter is null
/// on input the file system should not fill this value.
/// </param>
/// <returns>
/// STATUS_SUCCESS, STATUS_REPARSE or error code.
/// STATUS_REPARSE should be returned by file systems that support reparse points when
/// they encounter a FileName that contains reparse points anywhere but the final path
/// component.
/// </returns>
public virtual Int32 GetSecurityByName(
String FileName,
out UInt32 FileAttributes/* or ReparsePointIndex */,
@ -85,6 +142,40 @@ namespace Fsp
FileAttributes = default(UInt32);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Creates a new file or directory.
/// </summary>
/// <param name="FileName">
/// The name of the file or directory to be created.
/// </param>
/// <param name="CreateOptions">
/// Create options for this request.
/// </param>
/// <param name="GrantedAccess">
/// Determines the specific access rights that have been granted for this request.
/// </param>
/// <param name="FileAttributes">
/// File attributes to apply to the newly created file or directory.
/// </param>
/// <param name="SecurityDescriptor">
/// Security descriptor to apply to the newly created file or directory.
/// </param>
/// <param name="AllocationSize">
/// Allocation size for the newly created file.
/// </param>
/// <param name="FileNode">
/// Receives the file node for the newly created file.
/// </param>
/// <param name="FileDesc">
/// Receives the file descriptor for the newly created file.
/// </param>
/// <param name="FileInfo">
/// Receives the file information for the newly created file.
/// </param>
/// <param name="NormalizedName">
/// Receives the normalized name for the newly created file.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Create(
String FileName,
UInt32 CreateOptions,
@ -103,6 +194,31 @@ namespace Fsp
NormalizedName = default(String);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Opens a file or directory.
/// </summary>
/// <param name="FileName">
/// The name of the file or directory to be opened.
/// </param>
/// <param name="CreateOptions">
/// Create options for this request.
/// </param>
/// <param name="GrantedAccess">
/// Determines the specific access rights that have been granted for this request.
/// </param>
/// <param name="FileNode">
/// Receives the file node for the newly opened file.
/// </param>
/// <param name="FileDesc">
/// Receives the file descriptor for the newly opened file.
/// </param>
/// <param name="FileInfo">
/// Receives the file information for the newly opened file.
/// </param>
/// <param name="NormalizedName">
/// Receives the normalized name for the newly opened file.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Open(
String FileName,
UInt32 CreateOptions,
@ -118,6 +234,29 @@ namespace Fsp
NormalizedName = default(String);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Overwrites a file.
/// </summary>
/// <param name="FileNode">
/// The file node for the file to be overwritten.
/// </param>
/// <param name="FileDesc">
/// The file descriptor for the file to be overwritten.
/// </param>
/// <param name="FileAttributes">
/// File attributes to apply to the overwritten file.
/// </param>
/// <param name="ReplaceFileAttributes">
/// When true the existing file attributes should be replaced with the new ones.
/// When false the existing file attributes should be merged (or'ed) with the new ones.
/// </param>
/// <param name="AllocationSize">
/// Allocation size for the overwritten file.
/// </param>
/// <param name="FileInfo">
/// Receives the updated file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Overwrite(
Object FileNode,
Object FileDesc,
@ -129,6 +268,64 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Cleans up a file or directory.
/// </summary>
/// <remarks>
/// <para>
/// When CreateFile is used to open or create a file the kernel creates a kernel mode file
/// object (type FILE_OBJECT) and a handle for it, which it returns to user-mode. The handle may
/// be duplicated (using DuplicateHandle), but all duplicate handles always refer to the same
/// file object. When all handles for a particular file object get closed (using CloseHandle)
/// the system sends a Cleanup request to the file system.
/// </para><para>
/// There will be a Cleanup operation for every Create or Open operation posted to the user mode
/// file system. However the Cleanup operation is not the final close operation on a file.
/// The file system must be ready to receive additional operations until close time. This is true
/// even when the file is being deleted!
/// </para><para>
/// The Flags parameter contains information about the cleanup operation:
/// <list>
/// <item>CleanupDelete -
/// An important function of the Cleanup operation is to complete a delete operation. Deleting
/// a file or directory in Windows is a three-stage process where the file is first opened, then
/// tested to see if the delete can proceed and if the answer is positive the file is then
/// deleted during Cleanup.
/// When this flag is set, this is the last outstanding cleanup for this particular file node.
/// </item>
/// <item>CleanupSetAllocationSize -
/// The NTFS and FAT file systems reset a file's allocation size when they receive the last
/// outstanding cleanup for a particular file node. User mode file systems that implement
/// allocation size and wish to duplicate the NTFS and FAT behavior can use this flag.
/// </item>
/// <item>CleanupSetArchiveBit -
/// File systems that support the archive bit should set the file node's archive bit when this
/// flag is set.
/// </item>
/// <item>CleanupSetLastAccessTime, CleanupSetLastWriteTime, CleanupSetChangeTime -
/// File systems should set the corresponding file time when each one of these flags is set.
/// Note that updating the last access time is expensive and a file system may choose to not
/// implement it.
/// </item>
/// </list>
/// </para><para>
/// There is no way to report failure of this operation. This is a Windows limitation.
/// </para>
/// </remarks>
/// <param name="FileNode">
/// The file node of the file or directory to cleanup.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to cleanup.
/// </param>
/// <param name="FileName">
/// The name of the file or directory to cleanup. Sent only when a Delete is requested.
/// </param>
/// <param name="Flags">
/// These flags determine whether the file was modified and whether to delete the file.
/// </param>
/// <seealso cref="CanDelete"/>
/// <seealso cref="Close"/>
public virtual void Cleanup(
Object FileNode,
Object FileDesc,
@ -136,11 +333,42 @@ namespace Fsp
UInt32 Flags)
{
}
/// <summary>
/// Closes a file or directory.
/// </summary>
/// <param name="FileNode">
/// The file node of the file or directory to close.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to close.
/// </param>
public virtual void Close(
Object FileNode,
Object FileDesc)
{
}
/// <summary>
/// Reads a file.
/// </summary>
/// <param name="FileNode">
/// The file node of the file to read.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to read.
/// </param>
/// <param name="Buffer">
/// Pointer to a buffer that receives the results of the read operation.
/// </param>
/// <param name="Offset">
/// Offset within the file to read from.
/// </param>
/// <param name="Length">
/// Length of data to read.
/// </param>
/// <param name="BytesTransferred">
/// Receives the actual number of bytes read.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Read(
Object FileNode,
Object FileDesc,
@ -152,6 +380,38 @@ namespace Fsp
BytesTransferred = default(UInt32);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Writes a file.
/// </summary>
/// <param name="FileNode">
/// The file node of the file to write.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to write.
/// </param>
/// <param name="Buffer">
/// Pointer to a buffer that receives the results of the write operation.
/// </param>
/// <param name="Offset">
/// Offset within the file to write to.
/// </param>
/// <param name="Length">
/// Length of data to write.
/// </param>
/// <param name="WriteToEndOfFile">
/// When true the file system must write to the current end of file. In this case the Offset
/// parameter will contain the value -1.
/// </param>
/// <param name="ConstrainedIo">
/// When true the file system must not extend the file (i.e. change the file size).
/// </param>
/// <param name="BytesTransferred">
/// Receives the actual number of bytes written.
/// </param>
/// <param name="FileInfo">
/// Receives the updated file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Write(
Object FileNode,
Object FileDesc,
@ -167,6 +427,24 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Flushes a file or volume.
/// </summary>
/// <remarks>
/// Note that the FSD will also flush all file/volume caches prior to invoking this operation.
/// </remarks>
/// <param name="FileNode">
/// The file node of the file to flush.
/// When this and the FileDesc parameter are null the whole volume is being flushed.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to flush.
/// When this and the FileNode parameter are null the whole volume is being flushed.
/// </param>
/// <param name="FileInfo">
/// Receives the updated file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Flush(
Object FileNode,
Object FileDesc,
@ -175,6 +453,19 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Gets file or directory information.
/// </summary>
/// <param name="FileNode">
/// The file node of the file to get information for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to get information for.
/// </param>
/// <param name="FileInfo">
/// Receives the file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 GetFileInfo(
Object FileNode,
Object FileDesc,
@ -183,6 +474,39 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Sets file or directory basic information.
/// </summary>
/// <param name="FileNode">
/// The file node of the file to set information for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to set information for.
/// </param>
/// <param name="FileAttributes">
/// File attributes to apply to the file or directory.
/// If the value -1 is sent, the file attributes should not be changed.
/// </param>
/// <param name="CreationTime">
/// Creation time to apply to the file or directory.
/// If the value 0 is sent, the creation time should not be changed.
/// </param>
/// <param name="LastAccessTime">
/// Last access time to apply to the file or directory.
/// If the value 0 is sent, the last access time should not be changed.
/// </param>
/// <param name="LastWriteTime">
/// Last write time to apply to the file or directory.
/// If the value 0 is sent, the last write time should not be changed.
/// </param>
/// <param name="ChangeTime">
/// Change time to apply to the file or directory.
/// If the value 0 is sent, the change time should not be changed.
/// </param>
/// <param name="FileInfo">
/// Receives the updated file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 SetBasicInfo(
Object FileNode,
Object FileDesc,
@ -196,6 +520,52 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Sets file/allocation size.
/// </summary>
/// <remarks>
/// <para>
/// This function is used to change a file's sizes. Windows file systems maintain two kinds
/// of sizes: the file size is where the End Of File (EOF) is, and the allocation size is the
/// actual size that a file takes up on the "disk".
/// </para><para>
/// The rules regarding file/allocation size are:
/// <list>
/// <item>
/// Allocation size must always be aligned to the allocation unit boundary. The allocation
/// unit is the product SectorSize * SectorsPerAllocationUnit. The FSD will always send
/// properly aligned allocation sizes when setting the allocation size.
/// </item>
/// <item>
/// Allocation size is always greater or equal to the file size.
/// </item>
/// <item>
/// A file size of more than the current allocation size will also extend the allocation
/// size to the next allocation unit boundary.
/// </item>
/// <item>
/// An allocation size of less than the current file size should also truncate the current
/// file size.
/// </item>
/// </list>
/// </para>
/// </remarks>
/// <param name="FileNode">
/// The file node of the file to set the file/allocation size for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file to set the file/allocation size for.
/// </param>
/// <param name="NewSize">
/// New file/allocation size to apply to the file.
/// </param>
/// <param name="SetAllocationSize">
/// If true, then the allocation size is being set. if false, then the file size is being set.
/// </param>
/// <param name="FileInfo">
/// Receives the updated file information.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 SetFileSize(
Object FileNode,
Object FileDesc,
@ -206,6 +576,20 @@ namespace Fsp
FileInfo = default(FileInfo);
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Determines whether a file or directory can be deleted.
/// </summary>
/// <param name="FileNode">
/// The file node of the file or directory to test for deletion.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to test for deletion.
/// </param>
/// <param name="FileName">
/// The name of the file or directory to test for deletion.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
/// <seealso cref="Cleanup"/>
public virtual Int32 CanDelete(
Object FileNode,
Object FileDesc,
@ -213,6 +597,37 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Renames a file or directory.
/// </summary>
/// <remarks>
/// The kernel mode FSD provides certain guarantees prior to posting a rename operation:
/// <list>
/// <item>
/// A file cannot be renamed if a file with the same name exists and has open handles.
/// </item>
/// <item>
/// A directory cannot be renamed if it or any of its subdirectories contains a file that
/// has open handles.
/// </item>
/// </list>
/// </remarks>
/// <param name="FileNode">
/// The file node of the file or directory to be renamed.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to be renamed.
/// </param>
/// <param name="FileName">
/// The current name of the file or directory to rename.
/// </param>
/// <param name="NewFileName">
/// The new name for the file or directory.
/// </param>
/// <param name="ReplaceIfExists">
/// Whether to replace a file that already exists at NewFileName.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 Rename(
Object FileNode,
Object FileDesc,
@ -222,6 +637,19 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Gets file or directory security descriptor.
/// </summary>
/// <param name="FileNode">
/// The file node of the file or directory to get the security descriptor for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to get the security descriptor for.
/// </param>
/// <param name="SecurityDescriptor">
/// Receives the file security descriptor.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 GetSecurity(
Object FileNode,
Object FileDesc,
@ -229,6 +657,23 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Sets file or directory security descriptor.
/// </summary>
/// <param name="FileNode">
/// The file node of the file or directory to set the security descriptor for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to set the security descriptor for.
/// </param>
/// <param name="Sections">
/// Describes what parts of the file or directory security descriptor should be modified.
/// </param>
/// <param name="SecurityDescriptor">
/// Describes the modifications to apply to the file or directory security descriptor.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
/// <seealso cref="ModifySecurityDescriptor"/>
public virtual Int32 SetSecurity(
Object FileNode,
Object FileDesc,
@ -237,6 +682,10 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Reads a directory.
/// </summary>
/// <seealso cref="ReadDirectoryEntry"/>
public virtual Int32 ReadDirectory(
Object FileNode,
Object FileDesc,
@ -249,6 +698,36 @@ namespace Fsp
return SeekableReadDirectory(FileNode, FileDesc, Pattern, Marker, Buffer, Length,
out BytesTransferred);
}
/// <summary>
/// Reads a directory entry.
/// </summary>
/// <param name="FileNode">
/// The file node of the directory to be read.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the directory to be read.
/// </param>
/// <param name="Pattern">
/// The pattern to match against files in this directory. Can be null. The file system
/// can choose to ignore this parameter as the FSD will always perform its own pattern
/// matching on the returned results.
/// </param>
/// <param name="Marker">
/// A file name that marks where in the directory to start reading. Files with names
/// that are greater than (not equal to) this marker (in the directory order determined
/// by the file system) should be returned. Can be null.
/// </param>
/// <param name="Context">
/// Can be used by the file system to track the ReadDirectory operation.
/// </param>
/// <param name="FileName">
/// Receives the file name for the directory entry.
/// </param>
/// <param name="FileInfo">
/// Receives the file information for the directory entry.
/// </param>
/// <returns>True if there are additional directory entries to return. False otherwise.</returns>
/// <seealso cref="ReadDirectory"/>
public virtual Boolean ReadDirectoryEntry(
Object FileNode,
Object FileDesc,
@ -262,6 +741,9 @@ namespace Fsp
FileInfo = default(FileInfo);
return false;
}
/// <summary>
/// Resolves reparse points.
/// </summary>
public virtual Int32 ResolveReparsePoints(
String FileName,
UInt32 ReparsePointIndex,
@ -289,6 +771,19 @@ namespace Fsp
Handle.Free();
}
}
/// <summary>
/// Gets a reparse point given a file name.
/// </summary>
/// <param name="FileName">
/// The name of the file or directory to get the reparse point for.
/// </param>
/// <param name="IsDirectory">
/// Determines whether the passed file name is assumed to be a directory.
/// </param>
/// <param name="ReparseData">
/// Receives the reparse data for the file or directory.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 GetReparsePointByName(
String FileName,
Boolean IsDirectory,
@ -296,6 +791,22 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Gets a reparse point.
/// </summary>
/// <param name="FileNode">
/// The file node of the reparse point.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the reparse point.
/// </param>
/// <param name="FileName">
/// The file name of the reparse point.
/// </param>
/// <param name="ReparseData">
/// Receives the reparse data for the reparse point.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 GetReparsePoint(
Object FileNode,
Object FileDesc,
@ -304,6 +815,22 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Sets a reparse point.
/// </summary>
/// <param name="FileNode">
/// The file node of the reparse point.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the reparse point.
/// </param>
/// <param name="FileName">
/// The file name of the reparse point.
/// </param>
/// <param name="ReparseData">
/// The new reparse data for the reparse point.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 SetReparsePoint(
Object FileNode,
Object FileDesc,
@ -312,6 +839,22 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Deletes a reparse point.
/// </summary>
/// <param name="FileNode">
/// The file node of the reparse point.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the reparse point.
/// </param>
/// <param name="FileName">
/// The file name of the reparse point.
/// </param>
/// <param name="ReparseData">
/// The reparse data for the reparse point.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public virtual Int32 DeleteReparsePoint(
Object FileNode,
Object FileDesc,
@ -320,6 +863,9 @@ namespace Fsp
{
return STATUS_INVALID_DEVICE_REQUEST;
}
/// <summary>
/// Gets named streams information.
/// </summary>
public virtual Int32 GetStreamInfo(
Object FileNode,
Object FileDesc,
@ -342,6 +888,28 @@ namespace Fsp
Api.FspFileSystemEndStreamInfo(Buffer, Length, out BytesTransferred);
return STATUS_SUCCESS;
}
/// <summary>
/// Gets named streams information entry.
/// </summary>
/// <param name="FileNode">
/// The file node of the file or directory to get stream information for.
/// </param>
/// <param name="FileDesc">
/// The file descriptor of the file or directory to get stream information for.
/// </param>
/// <param name="Context">
/// Can be used by the file system to track the GetStreamInfo operation.
/// </param>
/// <param name="StreamName">
/// Receives the stream name for the stream entry.
/// </param>
/// <param name="StreamSize">
/// Receives the stream size for the stream entry.
/// </param>
/// <param name="StreamAllocationSize">
/// Receives the stream allocation size for the stream entry.
/// </param>
/// <returns>True if there are additional stream entries to return. False otherwise.</returns>
public virtual Boolean GetStreamEntry(
Object FileNode,
Object FileDesc,
@ -357,14 +925,37 @@ namespace Fsp
}
/* helpers */
/// <summary>
/// Converts a Win32 error code to a Windows kernel status code.
/// </summary>
public static Int32 NtStatusFromWin32(UInt32 Error)
{
return Api.FspNtStatusFromWin32(Error);
}
/// <summary>
/// Converts a Windows kernel status code to a Win32 error code.
/// </summary>
public static UInt32 Win32FromNtStatus(Int32 Status)
{
return Api.FspWin32FromNtStatus(Status);
}
/// <summary>
/// Modifies a security descriptor.
/// </summary>
/// <remarks>
/// This is a helper for implementing the SetSecurity operation.
/// </remarks>
/// <param name="SecurityDescriptor">
/// The original security descriptor.
/// </param>
/// <param name="Sections">
/// Describes what parts of the file or directory security descriptor should be modified.
/// </param>
/// <param name="ModificationDescriptor">
/// Describes the modifications to apply to the file or directory security descriptor.
/// </param>
/// <returns>The modified security descriptor.</returns>
/// <seealso cref="SetSecurity"/>
public static byte[] ModifySecurityDescriptor(
Byte[] SecurityDescriptor,
AccessControlSections Sections,
@ -449,6 +1040,21 @@ namespace Fsp
Marker, Buffer, Length, out BytesTransferred);
return STATUS_SUCCESS;
}
/// <summary>
/// Finds a reparse point in file name.
/// </summary>
/// <remarks>
/// This is a helper for implementing the GetSecurityByName operation in file systems
/// that support reparse points.
/// </remarks>
/// <param name="FileName">
/// The name of the file or directory.
/// </param>
/// <param name="ReparsePointIndex">
/// Receives the index of the first reparse point within FileName.
/// </param>
/// <returns>True if a reparse point was found, false otherwise.</returns>
/// <seealso cref="GetSecurityByName"/>
public Boolean FindReparsePoint(
String FileName,
out UInt32 ReparsePointIndex)
@ -468,11 +1074,34 @@ namespace Fsp
Handle.Free();
}
}
/// <summary>
/// Gets the reparse tag from reparse data.
/// </summary>
/// <param name="ReparseData">
/// The reparse data to extract the reparse tag from.
/// </param>
/// <returns>The reparse tag.</returns>
public static UInt32 GetReparseTag(
Byte[] ReparseData)
{
return BitConverter.ToUInt32(ReparseData, 0);
}
/// <summary>
/// Tests whether reparse data can be replaced.
/// </summary>
/// <remarks>
/// This is a helper for implementing the SetReparsePoint/DeleteReparsePoint operation
/// in file systems that support reparse points.
/// </remarks>
/// <param name="CurrentReparseData">
/// The current reparse data.
/// </param>
/// <param name="ReplaceReparseData">
/// The replacement reparse data.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
/// <seealso cref="SetReparsePoint"/>
/// <seealso cref="DeleteReparsePoint"/>
public static Int32 CanReplaceReparsePoint(
Byte[] CurrentReparseData,
Byte[] ReplaceReparseData)

111
src/dotnet/FileSystemHost.cs
View File

@ -1,7 +1,7 @@
/**
* @file dotnet/FileSystemHost.cs
/*
* dotnet/FileSystemHost.cs
*
* @copyright 2015-2017 Bill Zissimopoulos
* Copyright 2015-2017 Bill Zissimopoulos
*/
/*
* This file is part of WinFsp.
@ -24,9 +24,16 @@ using Fsp.Interop;
namespace Fsp
{
/// <summary>
/// Provides a means to host (mount) a file system.
/// </summary>
public class FileSystemHost : IDisposable
{
/* ctor/dtor */
/// <summary>
/// Creates an instance of the FileSystemHost class.
/// </summary>
/// <param name="FileSystem">The file system to host.</param>
public FileSystemHost(FileSystemBase FileSystem)
{
_VolumeParams.Flags = VolumeParams.UmFileContextIsFullContext;
@ -36,6 +43,9 @@ namespace Fsp
{
Dispose(false);
}
/// <summary>
/// Unmounts the file system and releases all associated resources.
/// </summary>
public void Dispose()
{
lock (this)
@ -63,66 +73,107 @@ namespace Fsp
}
/* properties */
/// <summary>
/// Gets or sets the sector size used by the file system.
/// </summary>
public UInt16 SectorSize
{
get { return _VolumeParams.SectorSize; }
set { _VolumeParams.SectorSize = value; }
}
/// <summary>
/// Gets or sets the sectors per allocation unit used by the file system.
/// </summary>
public UInt16 SectorsPerAllocationUnit
{
get { return _VolumeParams.SectorsPerAllocationUnit; }
set { _VolumeParams.SectorsPerAllocationUnit = value; }
}
/// <summary>
/// Gets or sets the maximum path component length used by the file system.
/// </summary>
public UInt16 MaxComponentLength
{
get { return _VolumeParams.MaxComponentLength; }
set { _VolumeParams.MaxComponentLength = value; }
}
/// <summary>
/// Gets or sets the volume creation time.
/// </summary>
public UInt64 VolumeCreationTime
{
get { return _VolumeParams.VolumeCreationTime; }
set { _VolumeParams.VolumeCreationTime = value; }
}
/// <summary>
/// Gets or sets the volume serial number.
/// </summary>
public UInt32 VolumeSerialNumber
{
get { return _VolumeParams.VolumeSerialNumber; }
set { _VolumeParams.VolumeSerialNumber = value; }
}
/// <summary>
/// Gets or sets the file information timeout.
/// </summary>
public UInt32 FileInfoTimeout
{
get { return _VolumeParams.FileInfoTimeout; }
set { _VolumeParams.FileInfoTimeout = value; }
}
/// <summary>
/// Gets or sets a value that determines whether the file system is case sensitive.
/// </summary>
public Boolean CaseSensitiveSearch
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.CaseSensitiveSearch); }
set { _VolumeParams.Flags |= (value ? VolumeParams.CaseSensitiveSearch : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether a case insensitive file system
/// preserves case in file names.
/// </summary>
public Boolean CasePreservedNames
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.CasePreservedNames); }
set { _VolumeParams.Flags |= (value ? VolumeParams.CasePreservedNames : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether file names support unicode characters.
/// </summary>
public Boolean UnicodeOnDisk
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.UnicodeOnDisk); }
set { _VolumeParams.Flags |= (value ? VolumeParams.UnicodeOnDisk : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether the file system supports ACL security.
/// </summary>
public Boolean PersistentAcls
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.PersistentAcls); }
set { _VolumeParams.Flags |= (value ? VolumeParams.PersistentAcls : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether the file system supports reparse points.
/// </summary>
public Boolean ReparsePoints
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.ReparsePoints); }
set { _VolumeParams.Flags |= (value ? VolumeParams.ReparsePoints : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether the file system allows creation of
/// symbolic links without additional privileges.
/// </summary>
public Boolean ReparsePointsAccessCheck
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.ReparsePointsAccessCheck); }
set { _VolumeParams.Flags |= (value ? VolumeParams.ReparsePointsAccessCheck : 0); }
}
/// <summary>
/// Gets or sets a value that determines whether the file system supports named streams.
/// </summary>
public Boolean NamedStreams
{
get { return 0 != (_VolumeParams.Flags & VolumeParams.NamedStreams); }
@ -138,11 +189,17 @@ namespace Fsp
get { return 0 != (_VolumeParams.Flags & VolumeParams.PassQueryDirectoryPattern); }
set { _VolumeParams.Flags |= (value ? VolumeParams.PassQueryDirectoryPattern : 0); }
}
/// <summary>
/// Gets or sets the prefix for a network file system.
/// </summary>
public String Prefix
{
get { return _VolumeParams.GetPrefix(); }
set { _VolumeParams.SetPrefix(value); }
}
/// <summary>
/// Gets or sets the file system name.
/// </summary>
public String FileSystemName
{
get { return _VolumeParams.GetFileSystemName(); }
@ -150,12 +207,42 @@ namespace Fsp
}
/* control */
/// <summary>
/// Checks whether mounting a file system is possible.
/// </summary>
/// <param name="MountPoint">
/// The mount point for the new file system. A value of null means that
/// the file system should use the next available drive letter counting
/// downwards from Z: as its mount point.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public Int32 Preflight(String MountPoint)
{
return Api.FspFileSystemPreflight(
_VolumeParams.IsPrefixEmpty() ? "WinFsp.Disk" : "WinFsp.Net",
MountPoint);
}
/// <summary>
/// Mounts a file system.
/// </summary>
/// <param name="MountPoint">
/// The mount point for the new file system. A value of null means that
/// the file system should use the next available drive letter counting
/// downwards from Z: as its mount point.
/// </param>
/// <param name="SecurityDescriptor">
/// Security descriptor to use if mounting on (newly created) directory.
/// A value of null means the directory should be created with default
/// security.
/// </param>
/// <param name="Synchronized">
/// If true file system operations are synchronized using an exclusive lock.
/// </param>
/// <param name="DebugLog">
/// A value of 0 disables all debug logging.
/// A value of -1 enables all debug logging.
/// </param>
/// <returns></returns>
public Int32 Mount(String MountPoint,
Byte[] SecurityDescriptor = null,
Boolean Synchronized = false,
@ -216,10 +303,17 @@ namespace Fsp
}
return Result;
}
/// <summary>
/// Unmounts the file system and releases all associated resources.
/// </summary>
public void Unmount()
{
Dispose();
}
/// <summary>
/// Gets the file system mount point.
/// </summary>
/// <returns>The file system mount point.</returns>
public String MountPoint()
{
return IntPtr.Zero != _FileSystemPtr ?
@ -229,10 +323,21 @@ namespace Fsp
{
return _FileSystemPtr;
}
/// <summary>
/// Gets the hosted file system.
/// </summary>
/// <returns>The hosted file system.</returns>
public FileSystemBase FileSystem()
{
return _FileSystem;
}
/// <summary>
/// Sets the debug log file to use when debug logging is enabled.
/// </summary>
/// <param name="FileName">
/// The debug log file name. A value of "-" means standard error output.
/// </param>
/// <returns>STATUS_SUCCESS or error code.</returns>
public static Int32 SetDebugLogFile(String FileName)
{
return Api.SetDebugLogFile(FileName);

54
src/dotnet/Interop.cs
View File

@ -1,7 +1,7 @@
/**
* @file dotnet/Interop.cs
/*
* dotnet/Interop.cs
*
* @copyright 2015-2017 Bill Zissimopoulos
* Copyright 2015-2017 Bill Zissimopoulos
*/
/*
* This file is part of WinFsp.
@ -102,16 +102,28 @@ namespace Fsp.Interop
}
}
/// <summary>
/// Contains volume information about a file system.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct VolumeInfo
{
internal const int VolumeLabelSize = 32;
/// <summary>
/// Total size of volume in bytes.
/// </summary>
public UInt64 TotalSize;
/// <summary>
/// Free size of volume in bytes.
/// </summary>
public UInt64 FreeSize;
internal UInt16 VolumeLabelLength;
internal unsafe fixed UInt16 VolumeLabel[VolumeLabelSize];
/// <summary>
/// Sets the volume label.
/// </summary>
public unsafe void SetVolumeLabel(String Value)
{
fixed (UInt16 *P = VolumeLabel)
@ -126,18 +138,54 @@ namespace Fsp.Interop
}
}
/// <summary>
/// Contains metadata information about a file or directory.
/// </summary>
[StructLayout(LayoutKind.Sequential)]
public struct FileInfo
{
/// <summary>
/// The file or directory attributes.
/// </summary>
public UInt32 FileAttributes;
/// <summary>
/// The reparse tag of the file or directory.
/// This value is 0 if the file or directory is not a reparse point.
/// </summary>
public UInt32 ReparseTag;
/// <summary>
/// The allocation size of the file.
/// </summary>
public UInt64 AllocationSize;
/// <summary>
/// The file size of the file (end of file).
/// </summary>
public UInt64 FileSize;
/// <summary>
/// The time that the file or directory was created.
/// </summary>
public UInt64 CreationTime;
/// <summary>
/// The time that the file or directory was last accessed.
/// </summary>
public UInt64 LastAccessTime;
/// <summary>
/// The time that the file or direcotry was last modified.
/// </summary>
public UInt64 LastWriteTime;
/// <summary>
/// The time that the file or directory metadata was last modified.
/// </summary>
public UInt64 ChangeTime;
/// <summary>
/// A unique identifier that is associated with the file or directory.
/// Not all file systems support this value.
/// </summary>
public UInt64 IndexNumber;
/// <summary>
/// The number of hard links.
/// Not currently implemented. Set to 0.
/// </summary>
public UInt32 HardLinks;
}

37
src/dotnet/Service.cs
View File

@ -1,7 +1,7 @@
/**
* @file dotnet/Service.cs
/*
* dotnet/Service.cs
*
* @copyright 2015-2017 Bill Zissimopoulos
* Copyright 2015-2017 Bill Zissimopoulos
*/
/*
* This file is part of WinFsp.
@ -16,13 +16,16 @@
*/
using System;
using System.Runtime.InteropServices;
using Fsp.Interop;
namespace Fsp
{
/// <summary>
/// Provides the base class for a process that can be run as a service,
/// command line application or under the control of the WinFsp launcher.
/// </summary>
public class Service
{
/* const */
@ -31,6 +34,10 @@ namespace Fsp
public const UInt32 EVENTLOG_INFORMATION_TYPE = 0x0004;
/* ctor/dtor */
/// <summary>
/// Creates an instance of the Service class.
/// </summary>
/// <param name="ServiceName">The name of the service.</param>
public Service(String ServiceName)
{
Api.FspServiceCreate(ServiceName, _OnStart, _OnStop, null, out _ServicePtr);
@ -47,6 +54,10 @@ namespace Fsp
}
/* control */
/// <summary>
/// Runs a service.
/// </summary>
/// <returns>Service process exit code.</returns>
public int Run()
{
if (IntPtr.Zero == _ServicePtr)
@ -69,6 +80,9 @@ namespace Fsp
}
return ExitCode;
}
/// <summary>
/// Stops a running service.
/// </summary>
public void Stop()
{
if (IntPtr.Zero == _ServicePtr)
@ -81,6 +95,9 @@ namespace Fsp
throw new InvalidOperationException();
Api.FspServiceRequestTime(_ServicePtr, Time);
}
/// <summary>
/// Gets or sets the service process exit code.
/// </summary>
public int ExitCode
{
get
@ -106,13 +123,25 @@ namespace Fsp
}
/* start/stop */
/// <summary>
/// Provides a means to customize the returned status code when an exception happens.
/// </summary>
/// <param name="ex"></param>
/// <returns>STATUS_SUCCESS or error code.</returns>
protected virtual Int32 ExceptionHandler(Exception ex)
{
return unchecked((Int32)0xE0434f4D)/*STATUS_CLR_EXCEPTION*/;
}
/// <summary>
/// Occurs when the service starts.
/// </summary>
/// <param name="Args">Command line arguments passed to the service.</param>
protected virtual void OnStart(String[] Args)
{
}
/// <summary>
/// Occurs when the service stops.
/// </summary>
protected virtual void OnStop()
{
}