diff --git a/doc/WinFsp-API-launch.h.asciidoc b/doc/WinFsp-API-launch.h.asciidoc index f876106a..651d1a1d 100644 --- a/doc/WinFsp-API-launch.h.asciidoc +++ b/doc/WinFsp-API-launch.h.asciidoc @@ -1,5 +1,5 @@ = winfsp/launch.h -:author: (C) 2015-2018 Bill Zissimopoulos +:author: (C) 2015-2020 Bill Zissimopoulos :toc: preamble :toc-title: @@ -22,7 +22,7 @@ FSP_API NTSTATUS FspLaunchCallLauncherPipe( PWSTR *Argv, ULONG *Argl, PWSTR Buffer, - PULONG PSize, + PULONG PSize, PULONG PLauncherError); ---- @@ -51,6 +51,47 @@ reported through PLauncherError. This function is used to send a command to the launcher and receive a response. +*FspLaunchCallLauncherPipeEx* - Call launcher pipe. + +[source,c] +---- +FSP_API NTSTATUS FspLaunchCallLauncherPipeEx( + WCHAR Command, + ULONG Argc, + PWSTR *Argv, + ULONG *Argl, + PWSTR Buffer, + PULONG PSize, + BOOLEAN AllowImpersonation, + PULONG PLauncherError); +---- + +*Parameters* + +- _Command_ - Launcher command to send. For example, the 'L' launcher command instructs +the launcher to list all running service instances. +- _Argc_ - Command argument count. May be 0. +- _Argv_ - Command argument array. May be NULL. +- _Argl_ - Command argument length array. May be NULL. If this is NULL all command arguments +are assumed to be NULL-terminated strings. It is also possible for specific arguments +to be NULL-terminated; in this case pass -1 in the corresponding Argl position. +- _Buffer_ - Buffer that receives the command response. May be NULL. +- _PSize_ - Pointer to a ULONG. On input it contains the size of the Buffer. On output it +contains the number of bytes transferred. May be NULL. +- _AllowImpersonation_ - Allow caller to be impersonated by launcher. +- _PLauncherError_ - Receives the launcher error if any. This is always a Win32 error code. May not be NULL. + +*Return Value* + +STATUS$$_$$SUCCESS if the command is sent successfully to the launcher, even if the launcher +returns an error. Other status codes indicate a communication error. Launcher errors are +reported through PLauncherError. + +*Discussion* + +This function is used to send a command to the launcher and receive a response. + + *FspLaunchGetInfo* - Get information about a service instance. [source,c] @@ -146,6 +187,39 @@ returns an error. Other status codes indicate a communication error. Launcher er reported through PLauncherError. +*FspLaunchStartEx* - Start a service instance. + +[source,c] +---- +FSP_API NTSTATUS FspLaunchStartEx( + PWSTR ClassName, + PWSTR InstanceName, + ULONG Argc, + PWSTR *Argv, + BOOLEAN HasSecret, + BOOLEAN AllowImpersonation, + PULONG PLauncherError); +---- + +*Parameters* + +- _ClassName_ - Class name of the service instance to start. +- _InstanceName_ - Instance name of the service instance to start. +- _Argc_ - Service instance argument count. May be 0. +- _Argv_ - Service instance argument array. May be NULL. +- _HasSecret_ - Whether the last argument in Argv is assumed to be a secret (e.g. password) or not. +Secrets are passed to service instances through standard input rather than the command +line. +- _AllowImpersonation_ - Allow caller to be impersonated by launcher. +- _PLauncherError_ - Receives the launcher error if any. This is always a Win32 error code. May not be NULL. + +*Return Value* + +STATUS$$_$$SUCCESS if the command is sent successfully to the launcher, even if the launcher +returns an error. Other status codes indicate a communication error. Launcher errors are +reported through PLauncherError. + + *FspLaunchStop* - Stop a service instance. [source,c] @@ -251,10 +325,12 @@ typedef struct _FSP_LAUNCH_REG_RECORD { PWSTR WorkDirectory; PWSTR RunAs; PWSTR Security; - PVOID Reserved0[6]; + PWSTR AuthPackage; + PVOID Reserved0[5]; ULONG JobControl; ULONG Credentials; - ULONG Reserved1[6]; + ULONG AuthPackageId; + ULONG Reserved1[5]; UINT8 Buffer[]; } FSP_LAUNCH_REG_RECORD; ---- diff --git a/doc/WinFsp-API-winfsp.h.asciidoc b/doc/WinFsp-API-winfsp.h.asciidoc index 099c9dfc..80563d91 100644 --- a/doc/WinFsp-API-winfsp.h.asciidoc +++ b/doc/WinFsp-API-winfsp.h.asciidoc @@ -1,5 +1,5 @@ = winfsp/winfsp.h -:author: (C) 2015-2018 Bill Zissimopoulos +:author: (C) 2015-2020 Bill Zissimopoulos :toc: preamble :toc-title: @@ -87,9 +87,13 @@ 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. +NOTE: If both CanDelete and SetDelete are defined, SetDelete takes precedence. However +most file systems need only implement the CanDelete operation. + *See Also* - Cleanup +- SetDelete *Cleanup* - Cleanup a file. @@ -161,6 +165,7 @@ the file was modified/deleted. - Close - CanDelete +- SetDelete *Close* - Close a file. @@ -262,6 +267,66 @@ from this call. This information includes file attributes, file times, etc. STATUS$$_$$SUCCESS or error code. +*CreateEx* - Create new file or directory. + +[source,c] +---- +NTSTATUS ( *CreateEx)( + FSP_FILE_SYSTEM *FileSystem, + PWSTR FileName, + UINT32 CreateOptions, + UINT32 GrantedAccess, + UINT32 FileAttributes, + PSECURITY_DESCRIPTOR SecurityDescriptor, + UINT64 AllocationSize, + PVOID ExtraBuffer, + ULONG ExtraLength, + BOOLEAN ExtraBufferIsReparsePoint, + 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. +- _ExtraBuffer_ - Extended attributes or reparse point buffer. +- _ExtraLength_ - Extended attributes or reparse point buffer length. +- _ExtraBufferIsReparsePoint_ - FALSE: extra buffer is extended attributes; TRUE: extra buffer is reparse point. +- _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. + +*Discussion* + +This function works like Create, except that it also accepts an extra buffer that +may contain extended attributes or a reparse point. + +NOTE: If both Create and CreateEx are defined, CreateEx takes precedence. + + *DeleteReparsePoint* - Delete reparse point. [source,c] @@ -342,6 +407,37 @@ attributes, file times, etc. STATUS$$_$$SUCCESS or error code. +*GetEa* - Get extended attributes. + +[source,c] +---- +NTSTATUS ( *GetEa)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PFILE_FULL_EA_INFORMATION Ea, + ULONG EaLength, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file to get extended attributes for. +- _Ea_ - Extended attributes buffer. +- _EaLength_ - Extended attributes buffer length. +- _PBytesTransferred_ - [out] +Pointer to a memory location that will receive the actual number of bytes transferred. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*See Also* + +- SetEa +- FspFileSystemAddEa + + *GetFileInfo* - Get file or directory information. [source,c] @@ -581,6 +677,46 @@ from this call. This information includes file attributes, file times, etc. STATUS$$_$$SUCCESS or error code. +*OverwriteEx* - Overwrite a file. + +[source,c] +---- +NTSTATUS ( *OverwriteEx)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + UINT32 FileAttributes, + BOOLEAN ReplaceFileAttributes, + UINT64 AllocationSize, + PFILE_FULL_EA_INFORMATION Ea, + ULONG EaLength, + 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. +- _Ea_ - Extended attributes buffer. +- _EaLength_ - Extended attributes buffer length. +- _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 works like Overwrite, except that it also accepts EA (extended attributes). + +NOTE: If both Overwrite and OverwriteEx are defined, OverwriteEx takes precedence. + + *Read* - Read a file. [source,c] @@ -775,6 +911,82 @@ from this call. This information includes file attributes, file times, etc. STATUS$$_$$SUCCESS or error code. +*SetDelete* - Set the file delete flag. + +[source,c] +---- +NTSTATUS ( *SetDelete)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PWSTR FileName, + BOOLEAN DeleteFile); +---- + +*Parameters* + +- _FileSystem_ - The file system on which this request is posted. +- _FileContext_ - The file context of the file or directory to set the delete flag for. +- _FileName_ - The name of the file or directory to set the delete flag for. +- _DeleteFile_ - If set to TRUE the FSD indicates that the file will be deleted on Cleanup; otherwise +it will not be deleted. It is legal to receive multiple SetDelete calls for the same +file with different DeleteFile parameters. + +*Return Value* + +STATUS$$_$$SUCCESS or error code. + +*Discussion* + +This function sets a flag to indicates whether the FSD file should delete a file +when it is closed. 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. + +NOTE: If both CanDelete and SetDelete are defined, SetDelete takes precedence. However +most file systems need only implement the CanDelete operation. + +*See Also* + +- Cleanup +- CanDelete + + +*SetEa* - Set extended attributes. + +[source,c] +---- +NTSTATUS ( *SetEa)( + FSP_FILE_SYSTEM *FileSystem, + PVOID FileContext, + PFILE_FULL_EA_INFORMATION Ea, + ULONG EaLength, + 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 extended attributes for. +- _Ea_ - Extended attributes buffer. +- _EaLength_ - Extended attributes buffer length. +- _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. + +*See Also* + +- GetEa + + *SetFileSize* - Set file/allocation size. [source,c] @@ -1016,6 +1228,42 @@ This is a helper for implementing the ReadDirectory operation. - ReadDirectory +*FspFileSystemAddEa* - Add extended attribute to a buffer. + +[source,c] +---- +FSP_API BOOLEAN FspFileSystemAddEa( + PFILE_FULL_EA_INFORMATION SingleEa, + PFILE_FULL_EA_INFORMATION Ea, + ULONG EaLength, + PULONG PBytesTransferred); +---- + +*Parameters* + +- _SingleEa_ - The extended attribute to add. A value of NULL acts as an EOF marker for a GetEa +operation. +- _Ea_ - Pointer to a buffer that will receive the extended attribute. This should contain +the same value passed to the GetEa Ea parameter. +- _EaLength_ - Length of buffer. This should contain the same value passed to the GetEa +EaLength 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 GetEa PBytesTransferred parameter. + +*Return Value* + +TRUE if the extended attribute was added, FALSE if there was not enough space to add it. + +*Discussion* + +This is a helper for implementing the GetEa operation. + +*See Also* + +- GetEa + + *FspFileSystemAddStreamInfo* - Add named stream information to a buffer. [source,c] @@ -1124,6 +1372,40 @@ FSP_API VOID FspFileSystemDelete( - _FileSystem_ - The file system object. +*FspFileSystemEnumerateEa* - Enumerate extended attributes in a buffer. + +[source,c] +---- +FSP_API NTSTATUS FspFileSystemEnumerateEa( + FSP_FILE_SYSTEM *FileSystem, + NTSTATUS (*EnumerateEa)( + FSP_FILE_SYSTEM *FileSystem, + PVOID Context, + PFILE_FULL_EA_INFORMATION SingleEa), + PVOID Context, + PFILE_FULL_EA_INFORMATION Ea, + ULONG EaLength); +---- + +*Parameters* + +- _FileSystem_ - The file system object. +- _EnumerateEa_ - Pointer to function that receives a single extended attribute. The function +should return STATUS$$_$$SUCCESS or an error code if unsuccessful. +- _Context_ - User context to supply to EnumEa. +- _Ea_ - Extended attributes buffer. +- _EaLength_ - Extended attributes buffer length. + +*Return Value* + +STATUS$$_$$SUCCESS or error code from EnumerateEa. + +*Discussion* + +This is a helper for implementing the CreateEx and SetEa operations in file systems +that support extended attributes. + + *FspFileSystemFindReparsePoint* - Find reparse point in file name. [source,c] @@ -1174,6 +1456,23 @@ that support reparse points. - GetSecurityByName +*FspFileSystemGetEaPackedSize* - Get extended attribute "packed" size. This computation matches what NTFS reports. + +[source,c] +---- +static inline UINT32 FspFileSystemGetEaPackedSize( + PFILE_FULL_EA_INFORMATION SingleEa) +---- + +*Parameters* + +- _SingleEa_ - The extended attribute to get the size for. + +*Return Value* + +The packed size of the extended attribute. + + *FspFileSystemGetOpenFileInfo* - Get open information buffer. [source,c]