mirror of
https://github.com/winfsp/winfsp.git
synced 2025-04-22 08:23:05 -05:00
doc: update api reference
This commit is contained in:
Bill Zissimopoulos
parent
b7553925fb
commit
f93cdbfa91
@ -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;
|
||||
----
|
||||
|
||||
@ -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]
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user