From e231b9c662eae9cf5d7d67c6ada4f779a4c19c19 Mon Sep 17 00:00:00 2001 From: Bill Zissimopoulos Date: Tue, 6 Dec 2016 17:04:44 -0800 Subject: [PATCH] doc: add winfsp.h documentation in markdown format --- doc/winfsp.h.markdown | 1785 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1785 insertions(+) create mode 100644 doc/winfsp.h.markdown diff --git a/doc/winfsp.h.markdown b/doc/winfsp.h.markdown new file mode 100644 index 00000000..597e9a40 --- /dev/null +++ b/doc/winfsp.h.markdown @@ -0,0 +1,1785 @@ +# 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 Delete==TRUE. + +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, + BOOLEAN Delete); + +**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. +- _Delete_ \- Determines whether to delete the file. Note that there is no way to report failure of +this operation. Also note that when this parameter is TRUE this is the last outstanding +cleanup for this particular file node. + +**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! + +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. + +As an optimization a file system may specify the FSP\_FSCTL\_VOLUME\_PARAMS :: +PostCleanupOnDeleteOnly flag. In this case the FSD will only post Cleanup requests when a +file is being 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); + +**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. + +**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, + 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. +- _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. +- _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 it has any open handles, other than the one used to perform +the rename. + + +- 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, + 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. +- _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, + HANDLE AccessToken); + +**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. +- _AccessToken_ \- A handle to a token that can be used to verify whether the requested modifications +are allowed. + +**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, + HANDLE AccessToken, + 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. +- _AccessToken_ \- A handle to a token that can be used to verify whether the requested modifications +are allowed. This should contain the same value passed to the SetSecurity AccessToken +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