From 53e68942989203345a6ff7cb1aec97d28413ece0 Mon Sep 17 00:00:00 2001 From: Bill Zissimopoulos Date: Wed, 8 Feb 2017 17:36:17 -0800 Subject: [PATCH] doc: use asciidoc for winfsp.h reference --- doc/winfsp.h.asciidoc | 1741 +++++++++++++++++++++++++++++++++++++++ doc/winfsp.h.markdown | 1817 ----------------------------------------- 2 files changed, 1741 insertions(+), 1817 deletions(-) create mode 100644 doc/winfsp.h.asciidoc delete mode 100644 doc/winfsp.h.markdown diff --git a/doc/winfsp.h.asciidoc b/doc/winfsp.h.asciidoc new file mode 100644 index 00000000..1a397751 --- /dev/null +++ b/doc/winfsp.h.asciidoc @@ -0,0 +1,1741 @@ += winfsp/winfsp.h +:author: (C) 2015-2017 Bill Zissimopoulos +:toc: preamble +:toc-title: + +WinFsp User Mode API. + +In order to use the WinFsp API the user mode file system must include +and link with the winfsp$$_$$x64.dll (or winfsp$$_$$x86.dll) library. + +== File System + +A user mode file system is a program that uses the WinFsp API to expose a file system to +Windows. The user mode file system must implement the operations in FSP$$_$$FILE$$_$$SYSTEM$$_$$INTERFACE, +create a file system object using FspFileSystemCreate and start its dispatcher using +FspFileSystemStartDispatcher. At that point it will start receiving file system requests on the +FSP$$_$$FILE$$_$$SYSTEM$$_$$INTERFACE operations. + +=== Classes + +*FSP$$_$$FILE$$_$$SYSTEM$$_$$INTERFACE* - File system interface. + +*Discussion* + +The operations in this interface must be implemented by the user mode +file system. Not all operations need be implemented. For example, +a user mode file system that does not wish to support reparse points, +need not implement the reparse point operations. + +Most of the operations accept a FileContext parameter. This parameter +has different meanings depending on the value of the FSP$$_$$FSCTL$$_$$VOLUME$$_$$PARAMS +flags UmFileContextIsUserContext2 and UmFileContextIsFullContext. + +There are three cases to consider: + +- When both of these flags are unset (default), the FileContext parameter +represents the file node. The file node is a void pointer (or an integer +that can fit in a pointer) that is used to uniquely identify an open file. +Opening the same file name should always yield the same file node value +for as long as the file with that name remains open anywhere in the system. + + +- When the UmFileContextIsUserContext2 is set, the FileContext parameter +represents the file descriptor. The file descriptor is a void pointer (or +an integer that can fit in a pointer) that is used to identify an open +instance of a file. Opening the same file name may yield a different file +descriptor. + + +- When the UmFileContextIsFullContext is set, the FileContext parameter +is a pointer to a FSP$$_$$FSCTL$$_$$TRANSACT$$_$$FULL$$_$$CONTEXT. This allows a user mode +file system to access the low-level UserContext and UserContext2 values. +The UserContext is used to store the file node and the UserContext2 is +used to store the file descriptor for an open file. + +==== Member Functions + +*CanDelete* - Determine whether a file or directory can be deleted. + +[source,c] +---- +NTSTATUS ( *CanDelete)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to test for deletion. +- _FileName_ - The name of the file or directory to test for deletion. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This function tests whether a file or directory can be safely deleted. This function does +not need to perform access checks, but may performs tasks such as check for empty +directories, etc. + +This function should *NEVER* delete the file or directory in question. Deletion should +happen during Cleanup with the FspCleanupDelete flag set. + +This function gets called when Win32 API's such as DeleteFile or RemoveDirectory are used. +It does not get called when a file or directory is opened with FILE$$_$$DELETE$$_$$ON$$_$$CLOSE. + +*See Also* + +- Cleanup + + +*Cleanup* - Cleanup a file. + +[source,c] +---- +VOID ( *Cleanup)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + ULONG Flags); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to cleanup. +- _FileName_ - The name of the file or directory to cleanup. Sent only when a Delete is requested. +- _Flags_ - These flags determine whether the file was modified and whether to delete the file. + +*Discussion* + +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. + +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! + +The Flags parameter contains information about the cleanup operation: + +- FspCleanupDelete - +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. + + +- FspCleanupSetAllocationSize - +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. + + +- FspCleanupSetArchiveBit - +File systems that support the archive bit should set the file node's archive bit when this +flag is set. + + +- FspCleanupSetLastAccessTime, FspCleanupSetLastWriteTime, FspCleanupSetChangeTime - 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. + + + +There is no way to report failure of this operation. This is a Windows limitation. + +As an optimization a file system may specify the FSP$$_$$FSCTL$$_$$VOLUME$$_$$PARAMS $$::$$ +PostCleanupWhenModifiedOnly flag. In this case the FSD will only post Cleanup requests when +the file was modified/deleted. + +*See Also* + +- Close +- CanDelete + + +*Close* - Close a file. + +[source,c] +---- +VOID ( *Close)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to be closed. + + +*Create* - Create new file or directory. + +[source,c] +---- +NTSTATUS ( *Create)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR FileName, + UINT32 CreateOptions, + UINT32 GrantedAccess, + UINT32 FileAttributes, + PSECURITY_DESCRIPTOR SecurityDescriptor, + UINT64 AllocationSize, + PVOID *PFileContext, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileName_ - The name of the file or directory to be created. +- _CreateOptions_ - Create options for this request. This parameter has the same meaning as the +CreateOptions parameter of the NtCreateFile API. User mode file systems should typically +only be concerned with the flag FILE$$_$$DIRECTORY$$_$$FILE, which is an instruction to create a +directory rather than a file. Some file systems may also want to pay attention to the +FILE$$_$$NO$$_$$INTERMEDIATE$$_$$BUFFERING and FILE$$_$$WRITE$$_$$THROUGH flags, although these are +typically handled by the FSD component. +- _GrantedAccess_ - Determines the specific access rights that have been granted for this request. Upon +receiving this call all access checks have been performed and the user mode file system +need not perform any additional checks. However this parameter may be useful to a user +mode file system; for example the WinFsp-FUSE layer uses this parameter to determine +which flags to use in its POSIX open() call. +- _FileAttributes_ - File attributes to apply to the newly created file or directory. +- _SecurityDescriptor_ - Security descriptor to apply to the newly created file or directory. This security +descriptor will always be in self-relative format. Its length can be retrieved using the +Windows GetSecurityDescriptorLength API. Will be NULL for named streams. +- _AllocationSize_ - Allocation size for the newly created file. +- _PFileContext_ - [out] +Pointer that will receive the file context on successful return from this call. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*DeleteReparsePoint* - Delete reparse point. + +[source,c] +---- +NTSTATUS ( *DeleteReparsePoint)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + PVOID Buffer, + SIZE_T Size); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the reparse point. +- _FileName_ - The file name of the reparse point. +- _Buffer_ - Pointer to a buffer that contains the data for this operation. +- _Size_ - Size of data to write. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*Flush* - Flush a file or volume. + +[source,c] +---- +NTSTATUS ( *Flush)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to be flushed. When NULL the whole volume is being flushed. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. Used when +flushing file (not volume). + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +Note that the FSD will also flush all file/volume caches prior to invoking this operation. + + +*GetFileInfo* - Get file or directory information. + +[source,c] +---- +NTSTATUS ( *GetFileInfo)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to get information for. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*GetReparsePoint* - Get reparse point. + +[source,c] +---- +NTSTATUS ( *GetReparsePoint)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + PVOID Buffer, + PSIZE_T PSize); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the reparse point. +- _FileName_ - The file name of the reparse point. +- _Buffer_ - Pointer to a buffer that will receive the results of this operation. If +the function returns a symbolic link path, it should not be NULL terminated. +- _PSize_ - [in,out] +Pointer to the buffer size. On input it contains the size of the buffer. +On output it will contain the actual size of data copied. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*See Also* + +- SetReparsePoint + + +*GetSecurity* - Get file or directory security descriptor. + +[source,c] +---- +NTSTATUS ( *GetSecurity)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PSECURITY_DESCRIPTOR SecurityDescriptor, + SIZE_T *PSecurityDescriptorSize); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to get the security descriptor for. +- _SecurityDescriptor_ - Pointer to a buffer that will receive the file security descriptor on successful return +from this call. May be NULL. +- _PSecurityDescriptorSize_ - [in,out] +Pointer to the security descriptor buffer size. On input it contains the size of the +security descriptor buffer. On output it will contain the actual size of the security +descriptor copied into the security descriptor buffer. Cannot be NULL. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*GetSecurityByName* - Get file or directory attributes and security descriptor given a file name. + +[source,c] +---- +NTSTATUS ( *GetSecurityByName)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR FileName, + PUINT32 PFileAttributes/* or ReparsePointIndex */, + PSECURITY_DESCRIPTOR SecurityDescriptor, + SIZE_T *PSecurityDescriptorSize); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileName_ - The name of the file or directory to get the attributes and security descriptor for. +- _PFileAttributes_ - Pointer to a memory location that will receive the file attributes on successful return +from this call. May be NULL. + +If this call returns STATUS$$_$$REPARSE, the file system MAY place here the index of the +first reparse point within FileName. The file system MAY also leave this at its default +value of 0. +- _SecurityDescriptor_ - Pointer to a buffer that will receive the file security descriptor on successful return +from this call. May be NULL. +- _PSecurityDescriptorSize_ - [in,out] +Pointer to the security descriptor buffer size. On input it contains the size of the +security descriptor buffer. On output it will contain the actual size of the security +descriptor copied into the security descriptor buffer. May be NULL. + +*Return Value* + +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. + + +*GetStreamInfo* - Get named streams information. + +[source,c] +---- +NTSTATUS ( *GetStreamInfo)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PVOID Buffer, + ULONG Length, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to get stream information for. +- _Buffer_ - Pointer to a buffer that will receive the stream information. +- _Length_ - Length of buffer. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes stored. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*See Also* + +- FspFileSystemAddStreamInfo + + +*GetVolumeInfo* - Get volume information. + +[source,c] +---- +NTSTATUS ( *GetVolumeInfo)( + FSP_FILE_SYSTEM *FileSystem, + FSP_FSCTL_VOLUME_INFO *VolumeInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _VolumeInfo_ - [out] +Pointer to a structure that will receive the volume information on successful return +from this call. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*Open* - Open a file or directory. + +[source,c] +---- +NTSTATUS ( *Open)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR FileName, + UINT32 CreateOptions, + UINT32 GrantedAccess, + PVOID *PFileContext, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileName_ - The name of the file or directory to be opened. +- _CreateOptions_ - Create options for this request. This parameter has the same meaning as the +CreateOptions parameter of the NtCreateFile API. User mode file systems typically +do not need to do anything special with respect to this parameter. Some file systems may +also want to pay attention to the FILE$$_$$NO$$_$$INTERMEDIATE$$_$$BUFFERING and FILE$$_$$WRITE$$_$$THROUGH +flags, although these are typically handled by the FSD component. +- _GrantedAccess_ - Determines the specific access rights that have been granted for this request. Upon +receiving this call all access checks have been performed and the user mode file system +need not perform any additional checks. However this parameter may be useful to a user +mode file system; for example the WinFsp-FUSE layer uses this parameter to determine +which flags to use in its POSIX open() call. +- _PFileContext_ - [out] +Pointer that will receive the file context on successful return from this call. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*Overwrite* - Overwrite a file. + +[source,c] +---- +NTSTATUS ( *Overwrite)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + UINT32 FileAttributes, + BOOLEAN ReplaceFileAttributes, + UINT64 AllocationSize, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to overwrite. +- _FileAttributes_ - File attributes to apply to the overwritten file. +- _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. +- _AllocationSize_ - Allocation size for the overwritten file. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*Read* - Read a file. + +[source,c] +---- +NTSTATUS ( *Read)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PVOID Buffer, + UINT64 Offset, + ULONG Length, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to be read. +- _Buffer_ - Pointer to a buffer that will receive the results of the read operation. +- _Offset_ - Offset within the file to read from. +- _Length_ - Length of data to read. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes read. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. STATUS$$_$$PENDING is supported allowing for asynchronous +operation. + + +*ReadDirectory* - Read a directory. + +[source,c] +---- +NTSTATUS ( *ReadDirectory)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR Pattern, + PWSTR Marker, + PVOID Buffer, + ULONG Length, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the directory to be read. +- _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. +- _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. +- _Buffer_ - Pointer to a buffer that will receive the results of the read operation. +- _Length_ - Length of data to read. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes read. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. STATUS$$_$$PENDING is supported allowing for asynchronous +operation. + +*See Also* + +- FspFileSystemAddDirInfo + + +*Rename* - Renames a file or directory. + +[source,c] +---- +NTSTATUS ( *Rename)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + PWSTR NewFileName, + BOOLEAN ReplaceIfExists); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to be renamed. +- _FileName_ - The current name of the file or directory to rename. +- _NewFileName_ - The new name for the file or directory. +- _ReplaceIfExists_ - Whether to replace a file that already exists at NewFileName. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +The kernel mode FSD provides certain guarantees prior to posting a rename operation: + +- A file cannot be renamed if a file with the same name exists and has open handles. + + +- A directory cannot be renamed if it or any of its subdirectories contains a file that +has open handles. + + +*ResolveReparsePoints* - Resolve reparse points. + +[source,c] +---- +NTSTATUS ( *ResolveReparsePoints)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR FileName, + UINT32 ReparsePointIndex, + BOOLEAN ResolveLastPathComponent, + PIO_STATUS_BLOCK PIoStatus, + PVOID Buffer, + PSIZE_T PSize); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileName_ - The name of the file or directory to have its reparse points resolved. +- _ReparsePointIndex_ - The index of the first reparse point within FileName. +- _ResolveLastPathComponent_ - If FALSE, the last path component of FileName should not be resolved, even +if it is a reparse point that can be resolved. If TRUE, all path components +should be resolved if possible. +- _PIoStatus_ - Pointer to storage that will receive the status to return to the FSD. When +this function succeeds it must set PIoStatus->Status to STATUS$$_$$REPARSE and +PIoStatus->Information to either IO$$_$$REPARSE or the reparse tag. +- _Buffer_ - Pointer to a buffer that will receive the resolved file name (IO$$_$$REPARSE) or +reparse data (reparse tag). If the function returns a file name, it should +not be NULL terminated. +- _PSize_ - [in,out] +Pointer to the buffer size. On input it contains the size of the buffer. +On output it will contain the actual size of data copied. + +*Return Value* + +STATUS$$_$$REPARSE or error code. + +*Discussion* + +Reparse points are a general mechanism for attaching special behavior to files. +A file or directory can contain a reparse point. A reparse point is data that has +special meaning to the file system, Windows or user applications. For example, NTFS +and Windows use reparse points to implement symbolic links. As another example, +a particular file system may use reparse points to emulate UNIX FIFO's. + +This function is expected to resolve as many reparse points as possible. If a reparse +point is encountered that is not understood by the file system further reparse point +resolution should stop; the reparse point data should be returned to the FSD with status +STATUS$$_$$REPARSE/reparse-tag. If a reparse point (symbolic link) is encountered that is +understood by the file system but points outside it, the reparse point should be +resolved, but further reparse point resolution should stop; the resolved file name +should be returned to the FSD with status STATUS$$_$$REPARSE/IO$$_$$REPARSE. + + +*SetBasicInfo* - Set file or directory basic information. + +[source,c] +---- +NTSTATUS ( *SetBasicInfo)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + UINT32 FileAttributes, + UINT64 CreationTime, + UINT64 LastAccessTime, + UINT64 LastWriteTime, + UINT64 ChangeTime, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to set information for. +- _FileAttributes_ - File attributes to apply to the file or directory. If the value INVALID$$_$$FILE$$_$$ATTRIBUTES +is sent, the file attributes should not be changed. +- _CreationTime_ - Creation time to apply to the file or directory. If the value 0 is sent, the creation +time should not be changed. +- _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. +- _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. +- _ChangeTime_ - Change time to apply to the file or directory. If the value 0 is sent, the change time +should not be changed. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*SetFileSize* - Set file/allocation size. + +[source,c] +---- +NTSTATUS ( *SetFileSize)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + UINT64 NewSize, + BOOLEAN SetAllocationSize, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to set the file/allocation size for. +- _NewSize_ - New file/allocation size to apply to the file. +- _SetAllocationSize_ - If TRUE, then the allocation size is being set. if FALSE, then the file size is being set. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +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". + +The rules regarding file/allocation size are: + +- Allocation size must always be aligned to the allocation unit boundary. The allocation +unit is the product `(UINT64)SectorSize $$*$$ (UINT64)SectorsPerAllocationUnit` from +the FSP$$_$$FSCTL$$_$$VOLUME$$_$$PARAMS structure. The FSD will always send properly aligned allocation +sizes when setting the allocation size. + + +- Allocation size is always greater or equal to the file size. + + +- A file size of more than the current allocation size will also extend the allocation +size to the next allocation unit boundary. + + +- An allocation size of less than the current file size should also truncate the current +file size. + + +*SetReparsePoint* - Set reparse point. + +[source,c] +---- +NTSTATUS ( *SetReparsePoint)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + PVOID Buffer, + SIZE_T Size); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the reparse point. +- _FileName_ - The file name of the reparse point. +- _Buffer_ - Pointer to a buffer that contains the data for this operation. If this buffer +contains a symbolic link path, it should not be assumed to be NULL terminated. +- _Size_ - Size of data to write. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*See Also* + +- GetReparsePoint + + +*SetSecurity* - Set file or directory security descriptor. + +[source,c] +---- +NTSTATUS ( *SetSecurity)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + SECURITY_INFORMATION SecurityInformation, + PSECURITY_DESCRIPTOR ModificationDescriptor); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to set the security descriptor for. +- _SecurityInformation_ - Describes what parts of the file or directory security descriptor should +be modified. +- _ModificationDescriptor_ - Describes the modifications to apply to the file or directory security descriptor. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*See Also* + +- FspSetSecurityDescriptor +- FspDeleteSecurityDescriptor + + +*SetVolumeLabel* - Set volume label. + +[source,c] +---- +NTSTATUS ( *SetVolumeLabel)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR VolumeLabel, + FSP_FSCTL_VOLUME_INFO *VolumeInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _VolumeLabel_ - The new label for the volume. +- _VolumeInfo_ - [out] +Pointer to a structure that will receive the volume information on successful return +from this call. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*Write* - Write a file. + +[source,c] +---- +NTSTATUS ( *Write)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PVOID Buffer, + UINT64 Offset, + ULONG Length, + BOOLEAN WriteToEndOfFile, + BOOLEAN ConstrainedIo, + PULONG PBytesTransferred, + FSP_FSCTL_FILE_INFO *FileInfo); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to be written. +- _Buffer_ - Pointer to a buffer that contains the data to write. +- _Offset_ - Offset within the file to write to. +- _Length_ - Length of data to write. +- _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. +- _ConstrainedIo_ - When TRUE the file system must not extend the file (i.e. change the file size). +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes written. +- _FileInfo_ - [out] +Pointer to a structure that will receive the file information on successful return +from this call. This information includes file attributes, file times, etc. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. STATUS$$_$$PENDING is supported allowing for asynchronous +operation. + + + +=== Functions + +*FspDeleteSecurityDescriptor* - Delete security descriptor. + +[source,c] +---- +FSP_API VOID FspDeleteSecurityDescriptor( + PSECURITY_DESCRIPTOR SecurityDescriptor, + NTSTATUS (*CreateFunc)()); +---- + +*Parameters* + +- _SecurityDescriptor_ - The security descriptor to be deleted. +- _CreateFunc_ - Function used to create the security descriptor. This parameter should be +set to FspSetSecurityDescriptor for the public API. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This is a helper for implementing the SetSecurity operation. + +*See Also* + +- SetSecurity +- FspSetSecurityDescriptor + + +*FspFileSystemAddDirInfo* - Add directory information to a buffer. + +[source,c] +---- +FSP_API BOOLEAN FspFileSystemAddDirInfo( + FSP_FSCTL_DIR_INFO *DirInfo, + PVOID Buffer, + ULONG Length, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _DirInfo_ - The directory information to add. A value of NULL acts as an EOF marker for a ReadDirectory +operation. +- _Buffer_ - Pointer to a buffer that will receive the results of the read operation. This should contain +the same value passed to the ReadDirectory Buffer parameter. +- _Length_ - Length of data to read. This should contain the same value passed to the ReadDirectory +Length parameter. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes read. This should +contain the same value passed to the ReadDirectory PBytesTransferred parameter. +FspFileSystemAddDirInfo uses the value pointed by this parameter to track how much of the +buffer has been used so far. + +*Return Value* + +TRUE if the directory information was added, FALSE if there was not enough space to add it. + +*Discussion* + +This is a helper for implementing the ReadDirectory operation. + +*See Also* + +- ReadDirectory + + +*FspFileSystemAddStreamInfo* - Add named stream information to a buffer. + +[source,c] +---- +FSP_API BOOLEAN FspFileSystemAddStreamInfo( + FSP_FSCTL_STREAM_INFO *StreamInfo, + PVOID Buffer, + ULONG Length, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _StreamInfo_ - The stream information to add. A value of NULL acts as an EOF marker for a GetStreamInfo +operation. +- _Buffer_ - Pointer to a buffer that will receive the stream information. This should contain +the same value passed to the GetStreamInfo Buffer parameter. +- _Length_ - Length of buffer. This should contain the same value passed to the GetStreamInfo +Length parameter. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes stored. This should +contain the same value passed to the GetStreamInfo PBytesTransferred parameter. + +*Return Value* + +TRUE if the stream information was added, FALSE if there was not enough space to add it. + +*Discussion* + +This is a helper for implementing the GetStreamInfo operation. + +*See Also* + +- GetStreamInfo + + +*FspFileSystemCanReplaceReparsePoint* - Test whether reparse data can be replaced. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemCanReplaceReparsePoint( + PVOID CurrentReparseData, + SIZE_T CurrentReparseDataSize, + PVOID ReplaceReparseData, + SIZE_T ReplaceReparseDataSize); +---- + +*Parameters* + +- _CurrentReparseData_ - Pointer to the current reparse data. +- _CurrentReparseDataSize_ - Pointer to the current reparse data size. +- _ReplaceReparseData_ - Pointer to the replacement reparse data. +- _ReplaceReparseDataSize_ - Pointer to the replacement reparse data size. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This is a helper for implementing the SetReparsePoint/DeleteReparsePoint operation +in file systems that support reparse points. + +*See Also* + +- SetReparsePoint +- DeleteReparsePoint + + +*FspFileSystemCreate* - Create a file system object. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemCreate( + PWSTR DevicePath, + const FSP_FSCTL_VOLUME_PARAMS *VolumeParams, + const FSP_FILE_SYSTEM_INTERFACE *Interface, + FSP_FILE_SYSTEM **PFileSystem); +---- + +*Parameters* + +- _DevicePath_ - The name of the control device for this file system. This must be either +FSP$$_$$FSCTL$$_$$DISK$$_$$DEVICE$$_$$NAME or FSP$$_$$FSCTL$$_$$NET$$_$$DEVICE$$_$$NAME. +- _VolumeParams_ - Volume parameters for the newly created file system. +- _Interface_ - A pointer to the actual operations that actually implement this user mode file system. +- _PFileSystem_ - [out] +Pointer that will receive the file system object created on successful return from this +call. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*FspFileSystemDelete* - Delete a file system object. + +[source,c] +---- +FSP_API VOID FspFileSystemDelete( + FSP_FILE_SYSTEM *FileSystem); +---- + +*Parameters* + +- _FileSystem_ - The file system object. + + +*FspFileSystemFindReparsePoint* - Find reparse point in file name. + +[source,c] +---- +FSP_API BOOLEAN FspFileSystemFindReparsePoint( + FSP_FILE_SYSTEM *FileSystem, + NTSTATUS (*GetReparsePointByName)( + FSP_FILE_SYSTEM *FileSystem, + PVOID Context, + PWSTR FileName, + BOOLEAN IsDirectory, + PVOID Buffer, + PSIZE_T PSize), + PVOID Context, + PWSTR FileName, + PUINT32 PReparsePointIndex); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _GetReparsePointByName_ - Pointer to function that can retrieve reparse point information by name. The +FspFileSystemFindReparsePoint will call this function with the Buffer and PSize +arguments set to NULL. The function should return STATUS$$_$$SUCCESS if the passed +FileName is a reparse point or STATUS$$_$$NOT$$_$$A$$_$$REPARSE$$_$$POINT (or other error code) +otherwise. +- _Context_ - User context to supply to GetReparsePointByName. +- _FileName_ - The name of the file or directory. +- _PReparsePointIndex_ - Pointer to a memory location that will receive the index of the first reparse point +within FileName. A value is only placed in this memory location if the function returns +TRUE. May be NULL. + +*Return Value* + +TRUE if a reparse point was found, FALSE otherwise. + +*Discussion* + +Given a file name this function returns an index to the first path component that is a reparse +point. The function will call the supplied GetReparsePointByName function for every path +component until it finds a reparse point or the whole path is processed. + +This is a helper for implementing the GetSecurityByName operation in file systems +that support reparse points. + +*See Also* + +- GetSecurityByName + + +*FspFileSystemGetOpenFileInfo* - Get open information buffer. + +[source,c] +---- +static inline FSP_FSCTL_OPEN_FILE_INFO *FspFileSystemGetOpenFileInfo( + FSP_FSCTL_FILE_INFO *FileInfo) +---- + +*Parameters* + +- _FileInfo_ - The FileInfo parameter as passed to Create or Open operation. + +*Return Value* + +A pointer to the open information buffer for this Create or Open operation. + +*Discussion* + +This is a helper for implementing the Create and Open operations. It cannot be used with +any other operations. + +The FileInfo parameter to Create and Open is typed as pointer to FSP$$_$$FSCTL$$_$$FILE$$_$$INFO. The +true type of this parameter is pointer to FSP$$_$$FSCTL$$_$$OPEN$$_$$FILE$$_$$INFO. This simple function +converts from one type to the other. + +The FSP$$_$$FSCTL$$_$$OPEN$$_$$FILE$$_$$INFO type contains a FSP$$_$$FSCTL$$_$$FILE$$_$$INFO as well as the fields +NormalizedName and NormalizedNameSize. These fields can be used for file name normalization. +File name normalization is used to ensure that the FSD and the OS know the correct case +of a newly opened file name. + +For case-sensitive file systems this functionality should be ignored. The FSD will always +assume that the normalized file name is the same as the file name used to open the file. + +For case-insensitive file systems this functionality may be ignored. In this case the FSD +will assume that the normalized file name is the upper case version of the file name used +to open the file. The file system will work correctly and the only way an application will +be able to tell that the file system does not preserve case in normalized file names is by +issuing a GetFinalPathNameByHandle API call (or NtQueryInformationFile with +FileNameInformation/FileNormalizedNameInformation). + +For case-insensitive file systems this functionality may also be used. In this case the +user mode file system may use the NormalizedName and NormalizedNameSize parameters to +report to the FSD the normalized file name. It should be noted that the normalized file +name may only differ in case from the file name used to open the file. The NormalizedName +field will point to a buffer that can receive the normalized file name. The +NormalizedNameSize field will contain the size of the normalized file name buffer. On +completion of the Create or Open operation it should contain the actual size of the +normalized file name copied into the normalized file name buffer. The normalized file name +should not contain a terminating zero. + +*See Also* + +- Create +- Open + + +*FspFileSystemGetOperationContext* - Get the current operation context. + +[source,c] +---- +FSP_API FSP_FILE_SYSTEM_OPERATION_CONTEXT *FspFileSystemGetOperationContext( + VOID); +---- + +*Return Value* + +The current operation context. + +*Discussion* + +This function may be used only when servicing one of the FSP$$_$$FILE$$_$$SYSTEM$$_$$INTERFACE operations. +The current operation context is stored in thread local storage. It allows access to the +Request and Response associated with this operation. + + +*FspFileSystemPreflight* - Check whether creating a file system object is possible. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemPreflight( + PWSTR DevicePath, + PWSTR MountPoint); +---- + +*Parameters* + +- _DevicePath_ - The name of the control device for this file system. This must be either +FSP$$_$$FSCTL$$_$$DISK$$_$$DEVICE$$_$$NAME or FSP$$_$$FSCTL$$_$$NET$$_$$DEVICE$$_$$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. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*FspFileSystemRemoveMountPoint* - Remove the mount point for a file system. + +[source,c] +---- +FSP_API VOID FspFileSystemRemoveMountPoint( + FSP_FILE_SYSTEM *FileSystem); +---- + +*Parameters* + +- _FileSystem_ - The file system object. + + +*FspFileSystemResolveReparsePoints* - Resolve reparse points. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemResolveReparsePoints( + FSP_FILE_SYSTEM *FileSystem, + NTSTATUS (*GetReparsePointByName)( + FSP_FILE_SYSTEM *FileSystem, + PVOID Context, + PWSTR FileName, + BOOLEAN IsDirectory, + PVOID Buffer, + PSIZE_T PSize), + PVOID Context, + PWSTR FileName, + UINT32 ReparsePointIndex, + BOOLEAN ResolveLastPathComponent, + PIO_STATUS_BLOCK PIoStatus, + PVOID Buffer, + PSIZE_T PSize); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _GetReparsePointByName_ - Pointer to function that can retrieve reparse point information by name. The function +should return STATUS$$_$$SUCCESS if the passed FileName is a reparse point or +STATUS$$_$$NOT$$_$$A$$_$$REPARSE$$_$$POINT (or other error code) otherwise. +- _Context_ - User context to supply to GetReparsePointByName. +- _FileName_ - The name of the file or directory to have its reparse points resolved. +- _ReparsePointIndex_ - The index of the first reparse point within FileName. +- _ResolveLastPathComponent_ - If FALSE, the last path component of FileName should not be resolved, even +if it is a reparse point that can be resolved. If TRUE, all path components +should be resolved if possible. +- _PIoStatus_ - Pointer to storage that will receive the status to return to the FSD. When +this function succeeds it must set PIoStatus->Status to STATUS$$_$$REPARSE and +PIoStatus->Information to either IO$$_$$REPARSE or the reparse tag. +- _Buffer_ - Pointer to a buffer that will receive the resolved file name (IO$$_$$REPARSE) or +reparse data (reparse tag). If the function returns a file name, it should +not be NULL terminated. +- _PSize_ - [in,out] +Pointer to the buffer size. On input it contains the size of the buffer. +On output it will contain the actual size of data copied. + +*Return Value* + +STATUS$$_$$REPARSE or error code. + +*Discussion* + +Given a file name (and an index where to start resolving) this function will attempt to +resolve as many reparse points as possible. The function will call the supplied +GetReparsePointByName function for every path component until it resolves the reparse points +or the whole path is processed. + +This is a helper for implementing the ResolveReparsePoints operation in file systems +that support reparse points. + +*See Also* + +- ResolveReparsePoints + + +*FspFileSystemSendResponse* - Send a response to the FSD. + +[source,c] +---- +FSP_API VOID FspFileSystemSendResponse( + FSP_FILE_SYSTEM *FileSystem, + FSP_FSCTL_TRANSACT_RSP *Response); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _Response_ - The response buffer. + +*Discussion* + +This call is not required when the user mode file system performs synchronous processing of +requests. It is possible however for the following FSP$$_$$FILE$$_$$SYSTEM$$_$$INTERFACE operations to be +processed asynchronously: + +- Read + + +- Write + + +- ReadDirectory + + + +These operations are allowed to return STATUS$$_$$PENDING to postpone sending a response to the FSD. +At a later time the file system can use FspFileSystemSendResponse to send the response. + + +*FspFileSystemSetMountPoint* - Set the mount point for a file system. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemSetMountPoint( + FSP_FILE_SYSTEM *FileSystem, + PWSTR MountPoint); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _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. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This function supports drive letters (X:) or directories as mount points: + +- Drive letters: Refer to the documentation of the DefineDosDevice Windows API +to better understand how they are created. + + +- Directories: They can be used as mount points for disk based file systems. They cannot +be used for network file systems. This is a limitation that Windows imposes on junctions. + + +*FspFileSystemSetOperationGuardStrategy* - Set file system locking strategy. + +[source,c] +---- +static inline VOID FspFileSystemSetOperationGuardStrategy( + FSP_FILE_SYSTEM *FileSystem, + FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY GuardStrategy) +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _GuardStrategy_ - The locking (guard) strategy. + +*See Also* + +- FSP$$_$$FILE$$_$$SYSTEM$$_$$OPERATION$$_$$GUARD$$_$$STRATEGY + + +*FspFileSystemStartDispatcher* - Start the file system dispatcher. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemStartDispatcher( + FSP_FILE_SYSTEM *FileSystem, + ULONG ThreadCount); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _ThreadCount_ - The number of threads for the file system dispatcher. A value of 0 will create a default +number of threads and should be chosen in most cases. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +The file system dispatcher is used to dispatch operations posted by the FSD to the user mode +file system. Once this call starts executing the user mode file system will start receiving +file system requests from the kernel. + + +*FspFileSystemStopDispatcher* - Stop the file system dispatcher. + +[source,c] +---- +FSP_API VOID FspFileSystemStopDispatcher( + FSP_FILE_SYSTEM *FileSystem); +---- + +*Parameters* + +- _FileSystem_ - The file system object. + + +*FspSetSecurityDescriptor* - Modify security descriptor. + +[source,c] +---- +FSP_API NTSTATUS FspSetSecurityDescriptor( + PSECURITY_DESCRIPTOR InputDescriptor, + SECURITY_INFORMATION SecurityInformation, + PSECURITY_DESCRIPTOR ModificationDescriptor, + PSECURITY_DESCRIPTOR *PSecurityDescriptor); +---- + +*Parameters* + +- _InputDescriptor_ - The input security descriptor to be modified. +- _SecurityInformation_ - Describes what parts of the InputDescriptor should be modified. This should contain +the same value passed to the SetSecurity SecurityInformation parameter. +- _ModificationDescriptor_ - Describes the modifications to apply to the InputDescriptor. This should contain +the same value passed to the SetSecurity ModificationDescriptor parameter. +- _PSecurityDescriptor_ - [out] +Pointer to a memory location that will receive the resulting security descriptor. +This security descriptor can be later freed using FspDeleteSecurityDescriptor. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This is a helper for implementing the SetSecurity operation. + +*See Also* + +- SetSecurity +- FspDeleteSecurityDescriptor + + +=== Typedefs + +*FSP$$_$$FILE$$_$$SYSTEM$$_$$OPERATION$$_$$GUARD$$_$$STRATEGY* - User mode file system locking strategy. + +[source,c] +---- +typedef enum { + FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY_FINE = 0, + FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY_COARSE, +} FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY; +---- + +*Discussion* + +Two concurrency models are provided: + +1. A fine-grained concurrency model where file system NAMESPACE accesses +are guarded using an exclusive-shared (read-write) lock. File I/O is not +guarded and concurrent reads/writes/etc. are possible. [Note that the FSD +will still apply an exclusive-shared lock PER INDIVIDUAL FILE, but it will +not limit I/O operations for different files.] +The fine-grained concurrency model applies the exclusive-shared lock as +follows: + +- EXCL: SetVolumeLabel, Flush(Volume), +Create, Cleanup(Delete), SetInformation(Rename) + + +- SHRD: GetVolumeInfo, Open, SetInformation(Disposition), ReadDirectory + + +- NONE: all other operations + + + +2. A coarse-grained concurrency model where all file system accesses are +guarded by a mutually exclusive lock. + +*See Also* + +- FspFileSystemSetOperationGuardStrategy + + +== Service Framework + +User mode file systems typically are run as Windows services. WinFsp provides an API to make +the creation of Windows services easier. This API is provided for convenience and is not +necessary to expose a user mode file system to Windows. + +=== Functions + +*FspServiceAcceptControl* - Configure the control codes that a service accepts. + +[source,c] +---- +FSP_API VOID FspServiceAcceptControl( + FSP_SERVICE *Service, + ULONG Control); +---- + +*Parameters* + +- _Service_ - The service object. +- _Control_ - The control codes to accept. Note that the SERVICE$$_$$ACCEPT$$_$$PAUSE$$_$$CONTINUE code is silently +ignored. + +*Discussion* + +This API should be used prior to Start operations. + + +*FspServiceAllowConsoleMode* - Allow a service to run in console mode. + +[source,c] +---- +FSP_API VOID FspServiceAllowConsoleMode( + FSP_SERVICE *Service); +---- + +*Parameters* + +- _Service_ - The service object. + +*Discussion* + +A service that is run in console mode runs with a console attached and outside the control of +the Service Control Manager. This is useful for debugging and testing a service during +development. + +User mode file systems that wish to use the WinFsp Launcher functionality must also use this +call. The WinFsp Launcher is a Windows service that can be configured to launch and manage +multiple instances of a user mode file system. + + +*FspServiceCreate* - Create a service object. + +[source,c] +---- +FSP_API NTSTATUS FspServiceCreate( + PWSTR ServiceName, + FSP_SERVICE_START *OnStart, + FSP_SERVICE_STOP *OnStop, + FSP_SERVICE_CONTROL *OnControl, + FSP_SERVICE **PService); +---- + +*Parameters* + +- _ServiceName_ - The name of the service. +- _OnStart_ - Function to call when the service starts. +- _OnStop_ - Function to call when the service stops. +- _OnControl_ - Function to call when the service receives a service control code. +- _PService_ - [out] +Pointer that will receive the service object created on successful return from this +call. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + + +*FspServiceDelete* - Delete a service object. + +[source,c] +---- +FSP_API VOID FspServiceDelete( + FSP_SERVICE *Service); +---- + +*Parameters* + +- _Service_ - The service object. + + +*FspServiceGetExitCode* - Get the service process exit code. + +[source,c] +---- +FSP_API ULONG FspServiceGetExitCode( + FSP_SERVICE *Service); +---- + +*Parameters* + +- _Service_ - The service object. + +*Return Value* + +Service process exit code. + + +*FspServiceIsInteractive* - Determine if the current process is running in user interactive mode. + +[source,c] +---- +FSP_API BOOLEAN FspServiceIsInteractive( + VOID); +---- + +*Return Value* + +TRUE if the process is running in running user interactive mode. + + +*FspServiceLog* - Log a service message. + +[source,c] +---- +FSP_API VOID FspServiceLog( + ULONG Type, + PWSTR Format, + ...); +---- + +*Parameters* + +- _Type_ - One of EVENTLOG$$_$$INFORMATION$$_$$TYPE, EVENTLOG$$_$$WARNING$$_$$TYPE, EVENTLOG$$_$$ERROR$$_$$TYPE. +- _Format_ - Format specification. This function uses the Windows wsprintf API for formatting. Refer to +that API's documentation for details on the format specification. + +*Discussion* + +This function can be used to log an arbitrary message to the Windows Event Log or to the current +console if running in user interactive mode. + + +*FspServiceLoop* - Run a service main loop. + +[source,c] +---- +FSP_API NTSTATUS FspServiceLoop( + FSP_SERVICE *Service); +---- + +*Parameters* + +- _Service_ - The service object. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This function starts and runs a service. It executes the Windows StartServiceCtrlDispatcher API +to connect the service process to the Service Control Manager. If the Service Control Manager is +not available (and console mode is allowed) it will enter console mode. + + +*FspServiceRequestTime* - Request additional time from the Service Control Manager. + +[source,c] +---- +FSP_API VOID FspServiceRequestTime( + FSP_SERVICE *Service, + ULONG Time); +---- + +*Parameters* + +- _Service_ - The service object. +- _Time_ - Additional time (in milliseconds). + +*Discussion* + +This API should be used during Start and Stop operations only. + + +*FspServiceRunEx* - Run a service. + +[source,c] +---- +FSP_API ULONG FspServiceRunEx( + PWSTR ServiceName, + FSP_SERVICE_START *OnStart, + FSP_SERVICE_STOP *OnStop, + FSP_SERVICE_CONTROL *OnControl, + PVOID UserContext); +---- + +*Parameters* + +- _ServiceName_ - The name of the service. +- _OnStart_ - Function to call when the service starts. +- _OnStop_ - Function to call when the service stops. +- _OnControl_ - Function to call when the service receives a service control code. + +*Return Value* + +Service process exit code. + +*Discussion* + +This function wraps calls to FspServiceCreate, FspServiceLoop and FspServiceDelete to create, +run and delete a service. It is intended to be used from a service's main/wmain function. + +This function runs a service with console mode allowed. + + +*FspServiceSetExitCode* - Set the service process exit code. + +[source,c] +---- +FSP_API VOID FspServiceSetExitCode( + FSP_SERVICE *Service, + ULONG ExitCode); +---- + +*Parameters* + +- _Service_ - The service object. +- _ExitCode_ - Service process exit code. + + +*FspServiceStop* - Stops a running service. + +[source,c] +---- +FSP_API VOID FspServiceStop( + FSP_SERVICE *Service); +---- + +*Parameters* + +- _Service_ - The service object. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +Stopping a service usually happens when the Service Control Manager instructs the service to +stop. In some situations (e.g. fatal errors) the service may wish to stop itself. It can do so +in a clean manner by calling this function. + + + diff --git a/doc/winfsp.h.markdown b/doc/winfsp.h.markdown deleted file mode 100644 index cbbceccd..00000000 --- a/doc/winfsp.h.markdown +++ /dev/null @@ -1,1817 +0,0 @@ -# winfsp/winfsp.h - -WinFsp User Mode API. - -## SYNOPSIS - -### FILE SYSTEM - -A user mode file system is a program that uses the WinFsp API to expose a file system to -Windows. The user mode file system must implement the operations in FSP\_FILE\_SYSTEM\_INTERFACE, -create a file system object using FspFileSystemCreate and start its dispatcher using -FspFileSystemStartDispatcher. At that point it will start receiving file system requests on the -FSP\_FILE\_SYSTEM\_INTERFACE operations. - -#### CLASSES - -**FSP\_FILE\_SYSTEM\_INTERFACE** - File system interface. - -#### MEMBER FUNCTIONS - -**CanDelete** - Determine whether a file or directory can be deleted. - -**Cleanup** - Cleanup a file. - -**Close** - Close a file. - -**Create** - Create new file or directory. - -**DeleteReparsePoint** - Delete reparse point. - -**Flush** - Flush a file or volume. - -**GetFileInfo** - Get file or directory information. - -**GetReparsePoint** - Get reparse point. - -**GetSecurity** - Get file or directory security descriptor. - -**GetSecurityByName** - Get file or directory attributes and security descriptor given a file name. - -**GetStreamInfo** - Get named streams information. - -**GetVolumeInfo** - Get volume information. - -**Open** - Open a file or directory. - -**Overwrite** - Overwrite a file. - -**Read** - Read a file. - -**ReadDirectory** - Read a directory. - -**Rename** - Renames a file or directory. - -**ResolveReparsePoints** - Resolve reparse points. - -**SetBasicInfo** - Set file or directory basic information. - -**SetFileSize** - Set file/allocation size. - -**SetReparsePoint** - Set reparse point. - -**SetSecurity** - Set file or directory security descriptor. - -**SetVolumeLabel** - Set volume label. - -**Write** - Write a file. - -#### FUNCTIONS - -**FspDeleteSecurityDescriptor** - Delete security descriptor. - -**FspFileSystemAddDirInfo** - Add directory information to a buffer. - -**FspFileSystemAddStreamInfo** - Add named stream information to a buffer. - -**FspFileSystemCanReplaceReparsePoint** - Test whether reparse data can be replaced. - -**FspFileSystemCreate** - Create a file system object. - -**FspFileSystemDelete** - Delete a file system object. - -**FspFileSystemFindReparsePoint** - Find reparse point in file name. - -**FspFileSystemGetOpenFileInfo** - Get open information buffer. - -**FspFileSystemGetOperationContext** - Get the current operation context. - -**FspFileSystemRemoveMountPoint** - Remove the mount point for a file system. - -**FspFileSystemResolveReparsePoints** - Resolve reparse points. - -**FspFileSystemSendResponse** - Send a response to the FSD. - -**FspFileSystemSetMountPoint** - Set the mount point for a file system. - -**FspFileSystemSetOperationGuardStrategy** - Set file system locking strategy. - -**FspFileSystemStartDispatcher** - Start the file system dispatcher. - -**FspFileSystemStopDispatcher** - Stop the file system dispatcher. - -**FspSetSecurityDescriptor** - Modify security descriptor. - -#### TYPEDEFS - -**FSP\_FILE\_SYSTEM\_OPERATION\_GUARD\_STRATEGY** - User mode file system locking strategy. - -### SERVICE FRAMEWORK - -User mode file systems typically are run as Windows services. WinFsp provides an API to make -the creation of Windows services easier. This API is provided for convenience and is not -necessary to expose a user mode file system to Windows. - -#### FUNCTIONS - -**FspServiceAcceptControl** - Configure the control codes that a service accepts. - -**FspServiceAllowConsoleMode** - Allow a service to run in console mode. - -**FspServiceCreate** - Create a service object. - -**FspServiceDelete** - Delete a service object. - -**FspServiceGetExitCode** - Get the service process exit code. - -**FspServiceIsInteractive** - Determine if the current process is running in user interactive mode. - -**FspServiceLog** - Log a service message. - -**FspServiceLoop** - Run a service main loop. - -**FspServiceRequestTime** - Request additional time from the Service Control Manager. - -**FspServiceRunEx** - Run a service. - -**FspServiceSetExitCode** - Set the service process exit code. - -**FspServiceStop** - Stops a running service. - -## DESCRIPTION - -In order to use the WinFsp API the user mode file system must include -and link with the winfsp\_x64.dll (or winfsp\_x86.dll) library. - -### FILE SYSTEM - -A user mode file system is a program that uses the WinFsp API to expose a file system to -Windows. The user mode file system must implement the operations in FSP\_FILE\_SYSTEM\_INTERFACE, -create a file system object using FspFileSystemCreate and start its dispatcher using -FspFileSystemStartDispatcher. At that point it will start receiving file system requests on the -FSP\_FILE\_SYSTEM\_INTERFACE operations. - -#### CLASSES - -**FSP\_FILE\_SYSTEM\_INTERFACE** - File system interface. - -**Discussion** - -The operations in this interface must be implemented by the user mode -file system. Not all operations need be implemented. For example, -a user mode file system that does not wish to support reparse points, -need not implement the reparse point operations. - -Most of the operations accept a FileContext parameter. This parameter -has different meanings depending on the value of the FSP\_FSCTL\_VOLUME\_PARAMS -flags UmFileContextIsUserContext2 and UmFileContextIsFullContext. - -There are three cases to consider: - -- When both of these flags are unset (default), the FileContext parameter -represents the file node. The file node is a void pointer (or an integer -that can fit in a pointer) that is used to uniquely identify an open file. -Opening the same file name should always yield the same file node value -for as long as the file with that name remains open anywhere in the system. - - -- When the UmFileContextIsUserContext2 is set, the FileContext parameter -represents the file descriptor. The file descriptor is a void pointer (or -an integer that can fit in a pointer) that is used to identify an open -instance of a file. Opening the same file name may yield a different file -descriptor. - - -- When the UmFileContextIsFullContext is set, the FileContext parameter -is a pointer to a FSP\_FSCTL\_TRANSACT\_FULL\_CONTEXT. This allows a user mode -file system to access the low-level UserContext and UserContext2 values. -The UserContext is used to store the file node and the UserContext2 is -used to store the file descriptor for an open file. - -#### MEMBER FUNCTIONS - -**CanDelete** - Determine whether a file or directory can be deleted. - - :::c - NTSTATUS ( *CanDelete)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to test for deletion. -- _FileName_ \- The name of the file or directory to test for deletion. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This function tests whether a file or directory can be safely deleted. This function does -not need to perform access checks, but may performs tasks such as check for empty -directories, etc. - -This function should **NEVER** delete the file or directory in question. Deletion should -happen during Cleanup with the FspCleanupDelete flag set. - -This function gets called when Win32 API's such as DeleteFile or RemoveDirectory are used. -It does not get called when a file or directory is opened with FILE\_DELETE\_ON\_CLOSE. - -**See Also** - -- Cleanup - --------- - -**Cleanup** - Cleanup a file. - - :::c - VOID ( *Cleanup)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName, - ULONG Flags); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to cleanup. -- _FileName_ \- The name of the file or directory to cleanup. Sent only when a Delete is requested. -- _Flags_ \- These flags determine whether the file was modified and whether to delete the file. - -**Discussion** - -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. - -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! - -The Flags parameter contains information about the cleanup operation: - -- FspCleanupDelete - -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. - - -- FspCleanupSetAllocationSize - -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. - - -- FspCleanupSetArchiveBit - -File systems that support the archive bit should set the file node's archive bit when this -flag is set. - - -- FspCleanupSetLastAccessTime, FspCleanupSetLastWriteTime, FspCleanupSetChangeTime - 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. - - - -There is no way to report failure of this operation. This is a Windows limitation. - -As an optimization a file system may specify the FSP\_FSCTL\_VOLUME\_PARAMS :: -PostCleanupWhenModifiedOnly flag. In this case the FSD will only post Cleanup requests when -the file was modified/deleted. - -**See Also** - -- Close -- CanDelete - --------- - -**Close** - Close a file. - - :::c - VOID ( *Close)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to be closed. - --------- - -**Create** - Create new file or directory. - - :::c - NTSTATUS ( *Create)( - FSP_FILE_SYSTEM *FileSystem, - PWSTR FileName, - UINT32 CreateOptions, - UINT32 GrantedAccess, - UINT32 FileAttributes, - PSECURITY_DESCRIPTOR SecurityDescriptor, - UINT64 AllocationSize, - PVOID *PFileContext, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileName_ \- The name of the file or directory to be created. -- _CreateOptions_ \- Create options for this request. This parameter has the same meaning as the -CreateOptions parameter of the NtCreateFile API. User mode file systems should typically -only be concerned with the flag FILE\_DIRECTORY\_FILE, which is an instruction to create a -directory rather than a file. Some file systems may also want to pay attention to the -FILE\_NO\_INTERMEDIATE\_BUFFERING and FILE\_WRITE\_THROUGH flags, although these are -typically handled by the FSD component. -- _GrantedAccess_ \- Determines the specific access rights that have been granted for this request. Upon -receiving this call all access checks have been performed and the user mode file system -need not perform any additional checks. However this parameter may be useful to a user -mode file system; for example the WinFsp-FUSE layer uses this parameter to determine -which flags to use in its POSIX open() call. -- _FileAttributes_ \- File attributes to apply to the newly created file or directory. -- _SecurityDescriptor_ \- Security descriptor to apply to the newly created file or directory. This security -descriptor will always be in self-relative format. Its length can be retrieved using the -Windows GetSecurityDescriptorLength API. Will be NULL for named streams. -- _AllocationSize_ \- Allocation size for the newly created file. -- _PFileContext_ \- [out] -Pointer that will receive the file context on successful return from this call. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**DeleteReparsePoint** - Delete reparse point. - - :::c - NTSTATUS ( *DeleteReparsePoint)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName, - PVOID Buffer, - SIZE_T Size); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the reparse point. -- _FileName_ \- The file name of the reparse point. -- _Buffer_ \- Pointer to a buffer that contains the data for this operation. -- _Size_ \- Size of data to write. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**Flush** - Flush a file or volume. - - :::c - NTSTATUS ( *Flush)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file to be flushed. When NULL the whole volume is being flushed. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. Used when -flushing file (not volume). - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -Note that the FSD will also flush all file/volume caches prior to invoking this operation. - --------- - -**GetFileInfo** - Get file or directory information. - - :::c - NTSTATUS ( *GetFileInfo)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to get information for. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**GetReparsePoint** - Get reparse point. - - :::c - NTSTATUS ( *GetReparsePoint)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName, - PVOID Buffer, - PSIZE_T PSize); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the reparse point. -- _FileName_ \- The file name of the reparse point. -- _Buffer_ \- Pointer to a buffer that will receive the results of this operation. If -the function returns a symbolic link path, it should not be NULL terminated. -- _PSize_ \- [in,out] -Pointer to the buffer size. On input it contains the size of the buffer. -On output it will contain the actual size of data copied. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**See Also** - -- SetReparsePoint - --------- - -**GetSecurity** - Get file or directory security descriptor. - - :::c - NTSTATUS ( *GetSecurity)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PSECURITY_DESCRIPTOR SecurityDescriptor, - SIZE_T *PSecurityDescriptorSize); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to get the security descriptor for. -- _SecurityDescriptor_ \- Pointer to a buffer that will receive the file security descriptor on successful return -from this call. May be NULL. -- _PSecurityDescriptorSize_ \- [in,out] -Pointer to the security descriptor buffer size. On input it contains the size of the -security descriptor buffer. On output it will contain the actual size of the security -descriptor copied into the security descriptor buffer. Cannot be NULL. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**GetSecurityByName** - Get file or directory attributes and security descriptor given a file name. - - :::c - NTSTATUS ( *GetSecurityByName)( - FSP_FILE_SYSTEM *FileSystem, - PWSTR FileName, - PUINT32 PFileAttributes/* or ReparsePointIndex */, - PSECURITY_DESCRIPTOR SecurityDescriptor, - SIZE_T *PSecurityDescriptorSize); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileName_ \- The name of the file or directory to get the attributes and security descriptor for. -- _PFileAttributes_ \- Pointer to a memory location that will receive the file attributes on successful return -from this call. May be NULL. - -If this call returns STATUS\_REPARSE, the file system MAY place here the index of the -first reparse point within FileName. The file system MAY also leave this at its default -value of 0. -- _SecurityDescriptor_ \- Pointer to a buffer that will receive the file security descriptor on successful return -from this call. May be NULL. -- _PSecurityDescriptorSize_ \- [in,out] -Pointer to the security descriptor buffer size. On input it contains the size of the -security descriptor buffer. On output it will contain the actual size of the security -descriptor copied into the security descriptor buffer. May be NULL. - -**Return Value** - -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. - --------- - -**GetStreamInfo** - Get named streams information. - - :::c - NTSTATUS ( *GetStreamInfo)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PVOID Buffer, - ULONG Length, - PULONG PBytesTransferred); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to get stream information for. -- _Buffer_ \- Pointer to a buffer that will receive the stream information. -- _Length_ \- Length of buffer. -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes stored. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**See Also** - -- FspFileSystemAddStreamInfo - --------- - -**GetVolumeInfo** - Get volume information. - - :::c - NTSTATUS ( *GetVolumeInfo)( - FSP_FILE_SYSTEM *FileSystem, - FSP_FSCTL_VOLUME_INFO *VolumeInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _VolumeInfo_ \- [out] -Pointer to a structure that will receive the volume information on successful return -from this call. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**Open** - Open a file or directory. - - :::c - NTSTATUS ( *Open)( - FSP_FILE_SYSTEM *FileSystem, - PWSTR FileName, - UINT32 CreateOptions, - UINT32 GrantedAccess, - PVOID *PFileContext, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileName_ \- The name of the file or directory to be opened. -- _CreateOptions_ \- Create options for this request. This parameter has the same meaning as the -CreateOptions parameter of the NtCreateFile API. User mode file systems typically -do not need to do anything special with respect to this parameter. Some file systems may -also want to pay attention to the FILE\_NO\_INTERMEDIATE\_BUFFERING and FILE\_WRITE\_THROUGH -flags, although these are typically handled by the FSD component. -- _GrantedAccess_ \- Determines the specific access rights that have been granted for this request. Upon -receiving this call all access checks have been performed and the user mode file system -need not perform any additional checks. However this parameter may be useful to a user -mode file system; for example the WinFsp-FUSE layer uses this parameter to determine -which flags to use in its POSIX open() call. -- _PFileContext_ \- [out] -Pointer that will receive the file context on successful return from this call. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**Overwrite** - Overwrite a file. - - :::c - NTSTATUS ( *Overwrite)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - UINT32 FileAttributes, - BOOLEAN ReplaceFileAttributes, - UINT64 AllocationSize, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file to overwrite. -- _FileAttributes_ \- File attributes to apply to the overwritten file. -- _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. -- _AllocationSize_ \- Allocation size for the overwritten file. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**Read** - Read a file. - - :::c - NTSTATUS ( *Read)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PVOID Buffer, - UINT64 Offset, - ULONG Length, - PULONG PBytesTransferred); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file to be read. -- _Buffer_ \- Pointer to a buffer that will receive the results of the read operation. -- _Offset_ \- Offset within the file to read from. -- _Length_ \- Length of data to read. -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes read. - -**Return Value** - -STATUS\_SUCCESS or error code. STATUS\_PENDING is supported allowing for asynchronous -operation. - --------- - -**ReadDirectory** - Read a directory. - - :::c - NTSTATUS ( *ReadDirectory)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PVOID Buffer, - UINT64 Offset, - ULONG Length, - PWSTR Pattern, - PULONG PBytesTransferred); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the directory to be read. -- _Buffer_ \- Pointer to a buffer that will receive the results of the read operation. -- _Offset_ \- Offset within the directory to read from. The kernel does not interpret this value -which is used solely by the file system to locate directory entries. However the -special value 0 indicates that the read should start from the first entries. The first -two entries returned by ReadDirectory should always be the "." and ".." entries, -except for the root directory which does not have these entries. - -This parameter is used by the WinFsp FSD to break directory listings into chunks. -In this case all 64-bits of the Offset are valid. In some cases the Windows kernel -(NTOS) may also use this parameter. In this case only the lower 32-bits of this -parameter will be valid. This is an unfortunate limitation of Windows (for more -information see the documentation for IRP\_MJ\_DIRECTORY\_CONTROL and the flag -SL\_INDEX\_SPECIFIED). - -In practice this means that you should only rely on the lower 32-bits of this value -to be valid. -- _Length_ \- Length of data to read. -- _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. -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes read. - -**Return Value** - -STATUS\_SUCCESS or error code. STATUS\_PENDING is supported allowing for asynchronous -operation. - -**See Also** - -- FspFileSystemAddDirInfo - --------- - -**Rename** - Renames a file or directory. - - :::c - NTSTATUS ( *Rename)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName, - PWSTR NewFileName, - BOOLEAN ReplaceIfExists); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to be renamed. -- _FileName_ \- The current name of the file or directory to rename. -- _NewFileName_ \- The new name for the file or directory. -- _ReplaceIfExists_ \- Whether to replace a file that already exists at NewFileName. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -The kernel mode FSD provides certain guarantees prior to posting a rename operation: - -- A file cannot be renamed if a file with the same name exists and has open handles. - - -- A directory cannot be renamed if it or any of its subdirectories contains a file that -has open handles. - --------- - -**ResolveReparsePoints** - Resolve reparse points. - - :::c - NTSTATUS ( *ResolveReparsePoints)( - FSP_FILE_SYSTEM *FileSystem, - PWSTR FileName, - UINT32 ReparsePointIndex, - BOOLEAN ResolveLastPathComponent, - PIO_STATUS_BLOCK PIoStatus, - PVOID Buffer, - PSIZE_T PSize); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileName_ \- The name of the file or directory to have its reparse points resolved. -- _ReparsePointIndex_ \- The index of the first reparse point within FileName. -- _ResolveLastPathComponent_ \- If FALSE, the last path component of FileName should not be resolved, even -if it is a reparse point that can be resolved. If TRUE, all path components -should be resolved if possible. -- _PIoStatus_ \- Pointer to storage that will receive the status to return to the FSD. When -this function succeeds it must set PIoStatus->Status to STATUS\_REPARSE and -PIoStatus->Information to either IO\_REPARSE or the reparse tag. -- _Buffer_ \- Pointer to a buffer that will receive the resolved file name (IO\_REPARSE) or -reparse data (reparse tag). If the function returns a file name, it should -not be NULL terminated. -- _PSize_ \- [in,out] -Pointer to the buffer size. On input it contains the size of the buffer. -On output it will contain the actual size of data copied. - -**Return Value** - -STATUS\_REPARSE or error code. - -**Discussion** - -Reparse points are a general mechanism for attaching special behavior to files. -A file or directory can contain a reparse point. A reparse point is data that has -special meaning to the file system, Windows or user applications. For example, NTFS -and Windows use reparse points to implement symbolic links. As another example, -a particular file system may use reparse points to emulate UNIX FIFO's. - -This function is expected to resolve as many reparse points as possible. If a reparse -point is encountered that is not understood by the file system further reparse point -resolution should stop; the reparse point data should be returned to the FSD with status -STATUS\_REPARSE/reparse-tag. If a reparse point (symbolic link) is encountered that is -understood by the file system but points outside it, the reparse point should be -resolved, but further reparse point resolution should stop; the resolved file name -should be returned to the FSD with status STATUS\_REPARSE/IO\_REPARSE. - --------- - -**SetBasicInfo** - Set file or directory basic information. - - :::c - NTSTATUS ( *SetBasicInfo)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - UINT32 FileAttributes, - UINT64 CreationTime, - UINT64 LastAccessTime, - UINT64 LastWriteTime, - UINT64 ChangeTime, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to set information for. -- _FileAttributes_ \- File attributes to apply to the file or directory. If the value INVALID\_FILE\_ATTRIBUTES -is sent, the file attributes should not be changed. -- _CreationTime_ \- Creation time to apply to the file or directory. If the value 0 is sent, the creation -time should not be changed. -- _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. -- _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. -- _ChangeTime_ \- Change time to apply to the file or directory. If the value 0 is sent, the change time -should not be changed. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**SetFileSize** - Set file/allocation size. - - :::c - NTSTATUS ( *SetFileSize)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - UINT64 NewSize, - BOOLEAN SetAllocationSize, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file to set the file/allocation size for. -- _NewSize_ \- New file/allocation size to apply to the file. -- _SetAllocationSize_ \- If TRUE, then the allocation size is being set. if FALSE, then the file size is being set. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -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". - -The rules regarding file/allocation size are: - -- Allocation size must always be aligned to the allocation unit boundary. The allocation -unit is the product `(UINT64)SectorSize \* (UINT64)SectorsPerAllocationUnit` from -the FSP\_FSCTL\_VOLUME\_PARAMS structure. The FSD will always send properly aligned allocation -sizes when setting the allocation size. - - -- Allocation size is always greater or equal to the file size. - - -- A file size of more than the current allocation size will also extend the allocation -size to the next allocation unit boundary. - - -- An allocation size of less than the current file size should also truncate the current -file size. - --------- - -**SetReparsePoint** - Set reparse point. - - :::c - NTSTATUS ( *SetReparsePoint)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PWSTR FileName, - PVOID Buffer, - SIZE_T Size); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the reparse point. -- _FileName_ \- The file name of the reparse point. -- _Buffer_ \- Pointer to a buffer that contains the data for this operation. If this buffer -contains a symbolic link path, it should not be assumed to be NULL terminated. -- _Size_ \- Size of data to write. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**See Also** - -- GetReparsePoint - --------- - -**SetSecurity** - Set file or directory security descriptor. - - :::c - NTSTATUS ( *SetSecurity)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - SECURITY_INFORMATION SecurityInformation, - PSECURITY_DESCRIPTOR ModificationDescriptor); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file or directory to set the security descriptor for. -- _SecurityInformation_ \- Describes what parts of the file or directory security descriptor should -be modified. -- _ModificationDescriptor_ \- Describes the modifications to apply to the file or directory security descriptor. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**See Also** - -- FspSetSecurityDescriptor -- FspDeleteSecurityDescriptor - --------- - -**SetVolumeLabel** - Set volume label. - - :::c - NTSTATUS ( *SetVolumeLabel)( - FSP_FILE_SYSTEM *FileSystem, - PWSTR VolumeLabel, - FSP_FSCTL_VOLUME_INFO *VolumeInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _VolumeLabel_ \- The new label for the volume. -- _VolumeInfo_ \- [out] -Pointer to a structure that will receive the volume information on successful return -from this call. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**Write** - Write a file. - - :::c - NTSTATUS ( *Write)( - FSP_FILE_SYSTEM *FileSystem, - PVOID FileContext, - PVOID Buffer, - UINT64 Offset, - ULONG Length, - BOOLEAN WriteToEndOfFile, - BOOLEAN ConstrainedIo, - PULONG PBytesTransferred, - FSP_FSCTL_FILE_INFO *FileInfo); - -**Parameters** - -- _FileSystem_ \- The file system on which this request is posted. -- _FileContext_ \- The file context of the file to be written. -- _Buffer_ \- Pointer to a buffer that contains the data to write. -- _Offset_ \- Offset within the file to write to. -- _Length_ \- Length of data to write. -- _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. -- _ConstrainedIo_ \- When TRUE the file system must not extend the file (i.e. change the file size). -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes written. -- _FileInfo_ \- [out] -Pointer to a structure that will receive the file information on successful return -from this call. This information includes file attributes, file times, etc. - -**Return Value** - -STATUS\_SUCCESS or error code. STATUS\_PENDING is supported allowing for asynchronous -operation. - --------- - --------- - -#### FUNCTIONS - -**FspDeleteSecurityDescriptor** - Delete security descriptor. - - :::c - FSP_API VOID FspDeleteSecurityDescriptor( - PSECURITY_DESCRIPTOR SecurityDescriptor, - NTSTATUS (*CreateFunc)()); - -**Parameters** - -- _SecurityDescriptor_ \- The security descriptor to be deleted. -- _CreateFunc_ \- Function used to create the security descriptor. This parameter should be -set to FspSetSecurityDescriptor for the public API. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This is a helper for implementing the SetSecurity operation. - -**See Also** - -- SetSecurity -- FspSetSecurityDescriptor - --------- - -**FspFileSystemAddDirInfo** - Add directory information to a buffer. - - :::c - FSP_API BOOLEAN FspFileSystemAddDirInfo( - FSP_FSCTL_DIR_INFO *DirInfo, - PVOID Buffer, - ULONG Length, - PULONG PBytesTransferred); - -**Parameters** - -- _DirInfo_ \- The directory information to add. A value of NULL acts as an EOF marker for a ReadDirectory -operation. -- _Buffer_ \- Pointer to a buffer that will receive the results of the read operation. This should contain -the same value passed to the ReadDirectory Buffer parameter. -- _Length_ \- Length of data to read. This should contain the same value passed to the ReadDirectory -Length parameter. -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes read. This should -contain the same value passed to the ReadDirectory PBytesTransferred parameter. -FspFileSystemAddDirInfo uses the value pointed by this parameter to track how much of the -buffer has been used so far. - -**Return Value** - -TRUE if the directory information was added, FALSE if there was not enough space to add it. - -**Discussion** - -This is a helper for implementing the ReadDirectory operation. - -**See Also** - -- ReadDirectory - --------- - -**FspFileSystemAddStreamInfo** - Add named stream information to a buffer. - - :::c - FSP_API BOOLEAN FspFileSystemAddStreamInfo( - FSP_FSCTL_STREAM_INFO *StreamInfo, - PVOID Buffer, - ULONG Length, - PULONG PBytesTransferred); - -**Parameters** - -- _StreamInfo_ \- The stream information to add. A value of NULL acts as an EOF marker for a GetStreamInfo -operation. -- _Buffer_ \- Pointer to a buffer that will receive the stream information. This should contain -the same value passed to the GetStreamInfo Buffer parameter. -- _Length_ \- Length of buffer. This should contain the same value passed to the GetStreamInfo -Length parameter. -- _PBytesTransferred_ \- [out] -Pointer to a memory location that will receive the actual number of bytes stored. This should -contain the same value passed to the GetStreamInfo PBytesTransferred parameter. - -**Return Value** - -TRUE if the stream information was added, FALSE if there was not enough space to add it. - -**Discussion** - -This is a helper for implementing the GetStreamInfo operation. - -**See Also** - -- GetStreamInfo - --------- - -**FspFileSystemCanReplaceReparsePoint** - Test whether reparse data can be replaced. - - :::c - FSP_API NTSTATUS FspFileSystemCanReplaceReparsePoint( - PVOID CurrentReparseData, - SIZE_T CurrentReparseDataSize, - PVOID ReplaceReparseData, - SIZE_T ReplaceReparseDataSize); - -**Parameters** - -- _CurrentReparseData_ \- Pointer to the current reparse data. -- _CurrentReparseDataSize_ \- Pointer to the current reparse data size. -- _ReplaceReparseData_ \- Pointer to the replacement reparse data. -- _ReplaceReparseDataSize_ \- Pointer to the replacement reparse data size. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This is a helper for implementing the SetReparsePoint/DeleteReparsePoint operation -in file systems that support reparse points. - -**See Also** - -- SetReparsePoint -- DeleteReparsePoint - --------- - -**FspFileSystemCreate** - Create a file system object. - - :::c - FSP_API NTSTATUS FspFileSystemCreate( - PWSTR DevicePath, - const FSP_FSCTL_VOLUME_PARAMS *VolumeParams, - const FSP_FILE_SYSTEM_INTERFACE *Interface, - FSP_FILE_SYSTEM **PFileSystem); - -**Parameters** - -- _DevicePath_ \- The name of the control device for this file system. This must be either -FSP\_FSCTL\_DISK\_DEVICE\_NAME or FSP\_FSCTL\_NET\_DEVICE\_NAME. -- _VolumeParams_ \- Volume parameters for the newly created file system. -- _Interface_ \- A pointer to the actual operations that actually implement this user mode file system. -- _PFileSystem_ \- [out] -Pointer that will receive the file system object created on successful return from this -call. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**FspFileSystemDelete** - Delete a file system object. - - :::c - FSP_API VOID FspFileSystemDelete( - FSP_FILE_SYSTEM *FileSystem); - -**Parameters** - -- _FileSystem_ \- The file system object. - --------- - -**FspFileSystemFindReparsePoint** - Find reparse point in file name. - - :::c - FSP_API BOOLEAN FspFileSystemFindReparsePoint( - FSP_FILE_SYSTEM *FileSystem, - NTSTATUS (*GetReparsePointByName)( - FSP_FILE_SYSTEM *FileSystem, - PVOID Context, - PWSTR FileName, - BOOLEAN IsDirectory, - PVOID Buffer, - PSIZE_T PSize), - PVOID Context, - PWSTR FileName, - PUINT32 PReparsePointIndex); - -**Parameters** - -- _FileSystem_ \- The file system object. -- _GetReparsePointByName_ \- Pointer to function that can retrieve reparse point information by name. The -FspFileSystemFindReparsePoint will call this function with the Buffer and PSize -arguments set to NULL. The function should return STATUS\_SUCCESS if the passed -FileName is a reparse point or STATUS\_NOT\_A\_REPARSE\_POINT (or other error code) -otherwise. -- _Context_ \- User context to supply to GetReparsePointByName. -- _FileName_ \- The name of the file or directory. -- _PReparsePointIndex_ \- Pointer to a memory location that will receive the index of the first reparse point -within FileName. A value is only placed in this memory location if the function returns -TRUE. May be NULL. - -**Return Value** - -TRUE if a reparse point was found, FALSE otherwise. - -**Discussion** - -Given a file name this function returns an index to the first path component that is a reparse -point. The function will call the supplied GetReparsePointByName function for every path -component until it finds a reparse point or the whole path is processed. - -This is a helper for implementing the GetSecurityByName operation in file systems -that support reparse points. - -**See Also** - -- GetSecurityByName - --------- - -**FspFileSystemGetOpenFileInfo** - Get open information buffer. - - :::c - static inline FSP_FSCTL_OPEN_FILE_INFO *FspFileSystemGetOpenFileInfo( - FSP_FSCTL_FILE_INFO *FileInfo) - -**Parameters** - -- _FileInfo_ \- The FileInfo parameter as passed to Create or Open operation. - -**Return Value** - -A pointer to the open information buffer for this Create or Open operation. - -**Discussion** - -This is a helper for implementing the Create and Open operations. It cannot be used with -any other operations. - -The FileInfo parameter to Create and Open is typed as pointer to FSP\_FSCTL\_FILE\_INFO. The -true type of this parameter is pointer to FSP\_FSCTL\_OPEN\_FILE\_INFO. This simple function -converts from one type to the other. - -The FSP\_FSCTL\_OPEN\_FILE\_INFO type contains a FSP\_FSCTL\_FILE\_INFO as well as the fields -NormalizedName and NormalizedNameSize. These fields can be used for file name normalization. -File name normalization is used to ensure that the FSD and the OS know the correct case -of a newly opened file name. - -For case-sensitive file systems this functionality should be ignored. The FSD will always -assume that the normalized file name is the same as the file name used to open the file. - -For case-insensitive file systems this functionality may be ignored. In this case the FSD -will assume that the normalized file name is the upper case version of the file name used -to open the file. The file system will work correctly and the only way an application will -be able to tell that the file system does not preserve case in normalized file names is by -issuing a GetFinalPathNameByHandle API call (or NtQueryInformationFile with -FileNameInformation/FileNormalizedNameInformation). - -For case-insensitive file systems this functionality may also be used. In this case the -user mode file system may use the NormalizedName and NormalizedNameSize parameters to -report to the FSD the normalized file name. It should be noted that the normalized file -name may only differ in case from the file name used to open the file. The NormalizedName -field will point to a buffer that can receive the normalized file name. The -NormalizedNameSize field will contain the size of the normalized file name buffer. On -completion of the Create or Open operation it should contain the actual size of the -normalized file name copied into the normalized file name buffer. The normalized file name -should not contain a terminating zero. - -**See Also** - -- Create -- Open - --------- - -**FspFileSystemGetOperationContext** - Get the current operation context. - - :::c - FSP_API FSP_FILE_SYSTEM_OPERATION_CONTEXT *FspFileSystemGetOperationContext( - VOID); - -**Return Value** - -The current operation context. - -**Discussion** - -This function may be used only when servicing one of the FSP\_FILE\_SYSTEM\_INTERFACE operations. -The current operation context is stored in thread local storage. It allows access to the -Request and Response associated with this operation. - --------- - -**FspFileSystemRemoveMountPoint** - Remove the mount point for a file system. - - :::c - FSP_API VOID FspFileSystemRemoveMountPoint( - FSP_FILE_SYSTEM *FileSystem); - -**Parameters** - -- _FileSystem_ \- The file system object. - --------- - -**FspFileSystemResolveReparsePoints** - Resolve reparse points. - - :::c - FSP_API NTSTATUS FspFileSystemResolveReparsePoints( - FSP_FILE_SYSTEM *FileSystem, - NTSTATUS (*GetReparsePointByName)( - FSP_FILE_SYSTEM *FileSystem, - PVOID Context, - PWSTR FileName, - BOOLEAN IsDirectory, - PVOID Buffer, - PSIZE_T PSize), - PVOID Context, - PWSTR FileName, - UINT32 ReparsePointIndex, - BOOLEAN ResolveLastPathComponent, - PIO_STATUS_BLOCK PIoStatus, - PVOID Buffer, - PSIZE_T PSize); - -**Parameters** - -- _FileSystem_ \- The file system object. -- _GetReparsePointByName_ \- Pointer to function that can retrieve reparse point information by name. The function -should return STATUS\_SUCCESS if the passed FileName is a reparse point or -STATUS\_NOT\_A\_REPARSE\_POINT (or other error code) otherwise. -- _Context_ \- User context to supply to GetReparsePointByName. -- _FileName_ \- The name of the file or directory to have its reparse points resolved. -- _ReparsePointIndex_ \- The index of the first reparse point within FileName. -- _ResolveLastPathComponent_ \- If FALSE, the last path component of FileName should not be resolved, even -if it is a reparse point that can be resolved. If TRUE, all path components -should be resolved if possible. -- _PIoStatus_ \- Pointer to storage that will receive the status to return to the FSD. When -this function succeeds it must set PIoStatus->Status to STATUS\_REPARSE and -PIoStatus->Information to either IO\_REPARSE or the reparse tag. -- _Buffer_ \- Pointer to a buffer that will receive the resolved file name (IO\_REPARSE) or -reparse data (reparse tag). If the function returns a file name, it should -not be NULL terminated. -- _PSize_ \- [in,out] -Pointer to the buffer size. On input it contains the size of the buffer. -On output it will contain the actual size of data copied. - -**Return Value** - -STATUS\_REPARSE or error code. - -**Discussion** - -Given a file name (and an index where to start resolving) this function will attempt to -resolve as many reparse points as possible. The function will call the supplied -GetReparsePointByName function for every path component until it resolves the reparse points -or the whole path is processed. - -This is a helper for implementing the ResolveReparsePoints operation in file systems -that support reparse points. - -**See Also** - -- ResolveReparsePoints - --------- - -**FspFileSystemSendResponse** - Send a response to the FSD. - - :::c - FSP_API VOID FspFileSystemSendResponse( - FSP_FILE_SYSTEM *FileSystem, - FSP_FSCTL_TRANSACT_RSP *Response); - -**Parameters** - -- _FileSystem_ \- The file system object. -- _Response_ \- The response buffer. - -**Discussion** - -This call is not required when the user mode file system performs synchronous processing of -requests. It is possible however for the following FSP\_FILE\_SYSTEM\_INTERFACE operations to be -processed asynchronously: - -- Read - - -- Write - - -- ReadDirectory - - - -These operations are allowed to return STATUS\_PENDING to postpone sending a response to the FSD. -At a later time the file system can use FspFileSystemSendResponse to send the response. - --------- - -**FspFileSystemSetMountPoint** - Set the mount point for a file system. - - :::c - FSP_API NTSTATUS FspFileSystemSetMountPoint( - FSP_FILE_SYSTEM *FileSystem, - PWSTR MountPoint); - -**Parameters** - -- _FileSystem_ \- The file system object. -- _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. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This function supports drive letters (X:) or directories as mount points: - -- Drive letters: Refer to the documentation of the DefineDosDevice Windows API -to better understand how they are created. - - -- Directories: They can be used as mount points for disk based file systems. They cannot -be used for network file systems. This is a limitation that Windows imposes on junctions. - --------- - -**FspFileSystemSetOperationGuardStrategy** - Set file system locking strategy. - - :::c - static inline VOID FspFileSystemSetOperationGuardStrategy( - FSP_FILE_SYSTEM *FileSystem, - FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY GuardStrategy) - -**Parameters** - -- _FileSystem_ \- The file system object. -- _GuardStrategy_ \- The locking (guard) strategy. - -**See Also** - -- FSP\_FILE\_SYSTEM\_OPERATION\_GUARD\_STRATEGY - --------- - -**FspFileSystemStartDispatcher** - Start the file system dispatcher. - - :::c - FSP_API NTSTATUS FspFileSystemStartDispatcher( - FSP_FILE_SYSTEM *FileSystem, - ULONG ThreadCount); - -**Parameters** - -- _FileSystem_ \- The file system object. -- _ThreadCount_ \- The number of threads for the file system dispatcher. A value of 0 will create a default -number of threads and should be chosen in most cases. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -The file system dispatcher is used to dispatch operations posted by the FSD to the user mode -file system. Once this call starts executing the user mode file system will start receiving -file system requests from the kernel. - --------- - -**FspFileSystemStopDispatcher** - Stop the file system dispatcher. - - :::c - FSP_API VOID FspFileSystemStopDispatcher( - FSP_FILE_SYSTEM *FileSystem); - -**Parameters** - -- _FileSystem_ \- The file system object. - --------- - -**FspSetSecurityDescriptor** - Modify security descriptor. - - :::c - FSP_API NTSTATUS FspSetSecurityDescriptor( - PSECURITY_DESCRIPTOR InputDescriptor, - SECURITY_INFORMATION SecurityInformation, - PSECURITY_DESCRIPTOR ModificationDescriptor, - PSECURITY_DESCRIPTOR *PSecurityDescriptor); - -**Parameters** - -- _InputDescriptor_ \- The input security descriptor to be modified. -- _SecurityInformation_ \- Describes what parts of the InputDescriptor should be modified. This should contain -the same value passed to the SetSecurity SecurityInformation parameter. -- _ModificationDescriptor_ \- Describes the modifications to apply to the InputDescriptor. This should contain -the same value passed to the SetSecurity ModificationDescriptor parameter. -- _PSecurityDescriptor_ \- [out] -Pointer to a memory location that will receive the resulting security descriptor. -This security descriptor can be later freed using FspDeleteSecurityDescriptor. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This is a helper for implementing the SetSecurity operation. - -**See Also** - -- SetSecurity -- FspDeleteSecurityDescriptor - --------- - -#### TYPEDEFS - -**FSP\_FILE\_SYSTEM\_OPERATION\_GUARD\_STRATEGY** - User mode file system locking strategy. - - :::c - typedef enum { - FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY_FINE = 0, - FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY_COARSE, - } FSP_FILE_SYSTEM_OPERATION_GUARD_STRATEGY; - -**Discussion** - -Two concurrency models are provided: - -1. A fine-grained concurrency model where file system NAMESPACE accesses -are guarded using an exclusive-shared (read-write) lock. File I/O is not -guarded and concurrent reads/writes/etc. are possible. [Note that the FSD -will still apply an exclusive-shared lock PER INDIVIDUAL FILE, but it will -not limit I/O operations for different files.] -The fine-grained concurrency model applies the exclusive-shared lock as -follows: - -- EXCL: SetVolumeLabel, Flush(Volume), -Create, Cleanup(Delete), SetInformation(Rename) - - -- SHRD: GetVolumeInfo, Open, SetInformation(Disposition), ReadDirectory - - -- NONE: all other operations - - - -2. A coarse-grained concurrency model where all file system accesses are -guarded by a mutually exclusive lock. - -**See Also** - -- FspFileSystemSetOperationGuardStrategy - --------- - -### SERVICE FRAMEWORK - -User mode file systems typically are run as Windows services. WinFsp provides an API to make -the creation of Windows services easier. This API is provided for convenience and is not -necessary to expose a user mode file system to Windows. - -#### FUNCTIONS - -**FspServiceAcceptControl** - Configure the control codes that a service accepts. - - :::c - FSP_API VOID FspServiceAcceptControl( - FSP_SERVICE *Service, - ULONG Control); - -**Parameters** - -- _Service_ \- The service object. -- _Control_ \- The control codes to accept. Note that the SERVICE\_ACCEPT\_PAUSE\_CONTINUE code is silently -ignored. - -**Discussion** - -This API should be used prior to Start operations. - --------- - -**FspServiceAllowConsoleMode** - Allow a service to run in console mode. - - :::c - FSP_API VOID FspServiceAllowConsoleMode( - FSP_SERVICE *Service); - -**Parameters** - -- _Service_ \- The service object. - -**Discussion** - -A service that is run in console mode runs with a console attached and outside the control of -the Service Control Manager. This is useful for debugging and testing a service during -development. - -User mode file systems that wish to use the WinFsp Launcher functionality must also use this -call. The WinFsp Launcher is a Windows service that can be configured to launch and manage -multiple instances of a user mode file system. - --------- - -**FspServiceCreate** - Create a service object. - - :::c - FSP_API NTSTATUS FspServiceCreate( - PWSTR ServiceName, - FSP_SERVICE_START *OnStart, - FSP_SERVICE_STOP *OnStop, - FSP_SERVICE_CONTROL *OnControl, - FSP_SERVICE **PService); - -**Parameters** - -- _ServiceName_ \- The name of the service. -- _OnStart_ \- Function to call when the service starts. -- _OnStop_ \- Function to call when the service stops. -- _OnControl_ \- Function to call when the service receives a service control code. -- _PService_ \- [out] -Pointer that will receive the service object created on successful return from this -call. - -**Return Value** - -STATUS\_SUCCESS or error code. - --------- - -**FspServiceDelete** - Delete a service object. - - :::c - FSP_API VOID FspServiceDelete( - FSP_SERVICE *Service); - -**Parameters** - -- _Service_ \- The service object. - --------- - -**FspServiceGetExitCode** - Get the service process exit code. - - :::c - FSP_API ULONG FspServiceGetExitCode( - FSP_SERVICE *Service); - -**Parameters** - -- _Service_ \- The service object. - -**Return Value** - -Service process exit code. - --------- - -**FspServiceIsInteractive** - Determine if the current process is running in user interactive mode. - - :::c - FSP_API BOOLEAN FspServiceIsInteractive( - VOID); - -**Return Value** - -TRUE if the process is running in running user interactive mode. - --------- - -**FspServiceLog** - Log a service message. - - :::c - FSP_API VOID FspServiceLog( - ULONG Type, - PWSTR Format, - ...); - -**Parameters** - -- _Type_ \- One of EVENTLOG\_INFORMATION\_TYPE, EVENTLOG\_WARNING\_TYPE, EVENTLOG\_ERROR\_TYPE. -- _Format_ \- Format specification. This function uses the Windows wsprintf API for formatting. Refer to -that API's documentation for details on the format specification. - -**Discussion** - -This function can be used to log an arbitrary message to the Windows Event Log or to the current -console if running in user interactive mode. - --------- - -**FspServiceLoop** - Run a service main loop. - - :::c - FSP_API NTSTATUS FspServiceLoop( - FSP_SERVICE *Service); - -**Parameters** - -- _Service_ \- The service object. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -This function starts and runs a service. It executes the Windows StartServiceCtrlDispatcher API -to connect the service process to the Service Control Manager. If the Service Control Manager is -not available (and console mode is allowed) it will enter console mode. - --------- - -**FspServiceRequestTime** - Request additional time from the Service Control Manager. - - :::c - FSP_API VOID FspServiceRequestTime( - FSP_SERVICE *Service, - ULONG Time); - -**Parameters** - -- _Service_ \- The service object. -- _Time_ \- Additional time (in milliseconds). - -**Discussion** - -This API should be used during Start and Stop operations only. - --------- - -**FspServiceRunEx** - Run a service. - - :::c - FSP_API ULONG FspServiceRunEx( - PWSTR ServiceName, - FSP_SERVICE_START *OnStart, - FSP_SERVICE_STOP *OnStop, - FSP_SERVICE_CONTROL *OnControl, - PVOID UserContext); - -**Parameters** - -- _ServiceName_ \- The name of the service. -- _OnStart_ \- Function to call when the service starts. -- _OnStop_ \- Function to call when the service stops. -- _OnControl_ \- Function to call when the service receives a service control code. - -**Return Value** - -Service process exit code. - -**Discussion** - -This function wraps calls to FspServiceCreate, FspServiceLoop and FspServiceDelete to create, -run and delete a service. It is intended to be used from a service's main/wmain function. - -This function runs a service with console mode allowed. - --------- - -**FspServiceSetExitCode** - Set the service process exit code. - - :::c - FSP_API VOID FspServiceSetExitCode( - FSP_SERVICE *Service, - ULONG ExitCode); - -**Parameters** - -- _Service_ \- The service object. -- _ExitCode_ \- Service process exit code. - --------- - -**FspServiceStop** - Stops a running service. - - :::c - FSP_API VOID FspServiceStop( - FSP_SERVICE *Service); - -**Parameters** - -- _Service_ \- The service object. - -**Return Value** - -STATUS\_SUCCESS or error code. - -**Discussion** - -Stopping a service usually happens when the Service Control Manager instructs the service to -stop. In some situations (e.g. fatal errors) the service may wish to stop itself. It can do so -in a clean manner by calling this function. - --------- - - -## COPYRIGHT - -(C) 2015-2016 Bill Zissimopoulos