mirror of
https://github.com/winfsp/winfsp.git
synced 2025-04-22 08:23:05 -05:00
doc: update API documentation
This commit is contained in:
Bill Zissimopoulos
parent
1208c6c652
commit
e823103334
@ -397,11 +397,13 @@ typedef struct _FSP_LAUNCH_REG_RECORD {
|
||||
PWSTR RunAs;
|
||||
PWSTR Security;
|
||||
PWSTR AuthPackage;
|
||||
PVOID Reserved0[5];
|
||||
PWSTR Stderr;
|
||||
PVOID Reserved0[4];
|
||||
ULONG JobControl;
|
||||
ULONG Credentials;
|
||||
ULONG AuthPackageId;
|
||||
ULONG Reserved1[5];
|
||||
ULONG Recovery;
|
||||
ULONG Reserved1[4];
|
||||
UINT8 Buffer[];
|
||||
} FSP_LAUNCH_REG_RECORD;
|
||||
```
|
||||
@ -414,7 +416,7 @@ typedef struct _FSP_LAUNCH_REG_RECORD {
|
||||
<br/>
|
||||
<p align="center">
|
||||
<sub>
|
||||
Copyright © 2015-2020 Bill Zissimopoulos
|
||||
Copyright © 2015-2021 Bill Zissimopoulos
|
||||
<br/>
|
||||
Generated with <a href="https://github.com/billziss-gh/prettydoc">prettydoc</a>
|
||||
</sub>
|
||||
|
||||
@ -83,6 +83,8 @@ STATUS\_SUCCESS or error code.
|
||||
|
||||
**Discussion**
|
||||
|
||||
(NOTE: use of this function is not recommended; use Delete instead.)
|
||||
|
||||
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.
|
||||
@ -100,6 +102,7 @@ most file systems need only implement the CanDelete operation.
|
||||
|
||||
- Cleanup
|
||||
- SetDelete
|
||||
- Delete
|
||||
|
||||
|
||||
</blockquote>
|
||||
@ -129,6 +132,9 @@ VOID ( *Cleanup)(
|
||||
|
||||
**Discussion**
|
||||
|
||||
(NOTE: use of this function with the FspCleanupDelete flag is not recommended;
|
||||
use Delete instead.)
|
||||
|
||||
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
|
||||
@ -179,6 +185,7 @@ the file was modified/deleted.
|
||||
- Close
|
||||
- CanDelete
|
||||
- SetDelete
|
||||
- Delete
|
||||
|
||||
|
||||
</blockquote>
|
||||
@ -368,6 +375,90 @@ may contain extended attributes or a reparse point.
|
||||
NOTE: If both Create and CreateEx are defined, CreateEx takes precedence.
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<b>Delete</b> - Set the file delete flag or delete a file.
|
||||
</summary>
|
||||
<blockquote>
|
||||
<br/>
|
||||
|
||||
```c
|
||||
NTSTATUS ( *Delete)(
|
||||
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 set the delete flag for.
|
||||
- _FileName_ \- The name of the file or directory to set the delete flag for.
|
||||
- _Flags_ \- File disposition flags
|
||||
|
||||
**Return Value**
|
||||
|
||||
STATUS\_SUCCESS or error code.
|
||||
|
||||
**Discussion**
|
||||
|
||||
This function replaces CanDelete, SetDelete and uses of Cleanup with the FspCleanupDelete flag
|
||||
and is recommended for use in all new code.
|
||||
|
||||
Due to the complexity of file deletion in the Windows file system this function is used
|
||||
in many scenarios. Its usage is controlled by the Flags parameter:
|
||||
|
||||
- FILE\_DISPOSITION\_DO\_NOT\_DELETE: Unmark the file for deletion.
|
||||
Do **NOT** delete the file either now or at Cleanup time.
|
||||
|
||||
|
||||
- FILE\_DISPOSITION\_DELETE: Mark the file for deletion,
|
||||
but do **NOT** delete the file. The file will be deleted at Cleanup time
|
||||
(via a call to Delete with Flags = -1).
|
||||
This function does not need to perform access checks, but may
|
||||
performs tasks such as check for empty directories, etc.
|
||||
|
||||
|
||||
- FILE\_DISPOSITION\_DELETE | FILE\_DISPOSITION\_POSIX\_SEMANTICS: Delete the file**NOW** using POSIX semantics. Open user mode handles to the file remain valid.
|
||||
This case will be received only when FSP\_FSCTL\_VOLUME\_PARAMS :: SupportsPosixUnlinkRename is set.
|
||||
|
||||
|
||||
- -1: Delete the file **NOW** using regular Windows semantics.
|
||||
Called during Cleanup with no open user mode handles remaining.
|
||||
If a file system implements Delete, Cleanup should **NOT** be used for deletion anymore.
|
||||
|
||||
|
||||
|
||||
This function gets called in all file deletion scenarios:
|
||||
|
||||
- When the DeleteFile or RemoveDirectory API's are used.
|
||||
|
||||
|
||||
- When the SetInformationByHandle API with FileDispositionInfo or FileDispositionInfoEx is used.
|
||||
|
||||
|
||||
- When a file is opened using FILE\_DELETE\_ON\_CLOSE.
|
||||
|
||||
|
||||
- Etc.
|
||||
|
||||
|
||||
|
||||
NOTE: Delete takes precedence over CanDelete, SetDelete and Cleanup with the FspCleanupDelete flag.
|
||||
This means that if Delete is defined, CanDelete and SetDelete will never be called and
|
||||
Cleanup will never be called with the FspCleanupDelete flag.
|
||||
|
||||
**See Also**
|
||||
|
||||
- Cleanup
|
||||
- CanDelete
|
||||
- SetDelete
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
@ -1111,6 +1202,8 @@ STATUS\_SUCCESS or error code.
|
||||
|
||||
**Discussion**
|
||||
|
||||
(NOTE: use of this function is not recommended; use Delete instead.)
|
||||
|
||||
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.
|
||||
@ -1128,6 +1221,7 @@ most file systems need only implement the CanDelete operation.
|
||||
|
||||
- Cleanup
|
||||
- CanDelete
|
||||
- Delete
|
||||
|
||||
|
||||
</blockquote>
|
||||
@ -1504,6 +1598,47 @@ This is a helper for implementing the GetEa operation.
|
||||
- GetEa
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<b>FspFileSystemAddNotifyInfo</b> - Add notify information to a buffer.
|
||||
</summary>
|
||||
<blockquote>
|
||||
<br/>
|
||||
|
||||
```c
|
||||
FSP_API BOOLEAN FspFileSystemAddNotifyInfo(
|
||||
FSP_FSCTL_NOTIFY_INFO *NotifyInfo,
|
||||
PVOID Buffer,
|
||||
ULONG Length,
|
||||
PULONG PBytesTransferred);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- _NotifyInfo_ \- The notify information to add.
|
||||
- _Buffer_ \- Pointer to a buffer that will receive the notify information.
|
||||
- _Length_ \- Length of buffer.
|
||||
- _PBytesTransferred_ \- [out]
|
||||
Pointer to a memory location that will receive the actual number of bytes stored. This should
|
||||
be initialized to 0 prior to the first call to FspFileSystemAddNotifyInfo for a particular
|
||||
buffer.
|
||||
|
||||
**Return Value**
|
||||
|
||||
TRUE if the notify information was added, FALSE if there was not enough space to add it.
|
||||
|
||||
**Discussion**
|
||||
|
||||
This is a helper for filling a buffer to use with FspFileSystemNotify.
|
||||
|
||||
**See Also**
|
||||
|
||||
- FspFileSystemNotify
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
@ -1851,6 +1986,123 @@ The current operation context is stored in thread local storage. It allows acces
|
||||
Request and Response associated with this operation.
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<b>FspFileSystemNotify</b> - Notify Windows that the file system has file changes.
|
||||
</summary>
|
||||
<blockquote>
|
||||
<br/>
|
||||
|
||||
```c
|
||||
FSP_API NTSTATUS FspFileSystemNotify(
|
||||
FSP_FILE_SYSTEM *FileSystem,
|
||||
FSP_FSCTL_NOTIFY_INFO *NotifyInfo,
|
||||
SIZE_T Size);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- _FileSystem_ \- The file system object.
|
||||
- _NotifyInfo_ \- Buffer containing information about file changes.
|
||||
- _Size_ \- Size of buffer.
|
||||
|
||||
**Return Value**
|
||||
|
||||
STATUS\_SUCCESS or error code.
|
||||
|
||||
**Discussion**
|
||||
|
||||
A file system that wishes to notify Windows about file changes must
|
||||
first issue an FspFileSystemBegin call, followed by 0 or more
|
||||
FspFileSystemNotify calls, followed by an FspFileSystemNotifyEnd call.
|
||||
|
||||
Note that FspFileSystemNotify requires file names to be normalized. A
|
||||
normalized file name is one that contains the correct case of all characters
|
||||
in the file name.
|
||||
|
||||
For case-sensitive file systems all file names are normalized by definition.
|
||||
For case-insensitive file systems that implement file name normalization,
|
||||
a normalized file name is the one that the file system specifies in the
|
||||
response to Create or Open (see also FspFileSystemGetOpenFileInfo). For
|
||||
case-insensitive file systems that do not implement file name normalization
|
||||
a normalized file name is the upper case version of the file name used
|
||||
to open the file.
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<b>FspFileSystemNotifyBegin</b> - Begin notifying Windows that the file system has file changes.
|
||||
</summary>
|
||||
<blockquote>
|
||||
<br/>
|
||||
|
||||
```c
|
||||
FSP_API NTSTATUS FspFileSystemNotifyBegin(
|
||||
FSP_FILE_SYSTEM *FileSystem,
|
||||
ULONG Timeout);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- _FileSystem_ \- The file system object.
|
||||
|
||||
**Return Value**
|
||||
|
||||
STATUS\_SUCCESS or error code. The error code STATUS\_CANT\_WAIT means that
|
||||
a file rename operation is currently in progress and the operation must be
|
||||
retried at a later time.
|
||||
|
||||
**Discussion**
|
||||
|
||||
A file system that wishes to notify Windows about file changes must
|
||||
first issue an FspFileSystemBegin call, followed by 0 or more
|
||||
FspFileSystemNotify calls, followed by an FspFileSystemNotifyEnd call.
|
||||
|
||||
This operation blocks concurrent file rename operations. File rename
|
||||
operations may interfere with file notification, because a file being
|
||||
notified may also be concurrently renamed. After all file change
|
||||
notifications have been issued, you must make sure to call
|
||||
FspFileSystemNotifyEnd to allow file rename operations to proceed.
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
<b>FspFileSystemNotifyEnd</b> - End notifying Windows that the file system has file changes.
|
||||
</summary>
|
||||
<blockquote>
|
||||
<br/>
|
||||
|
||||
```c
|
||||
FSP_API NTSTATUS FspFileSystemNotifyEnd(
|
||||
FSP_FILE_SYSTEM *FileSystem);
|
||||
```
|
||||
|
||||
**Parameters**
|
||||
|
||||
- _FileSystem_ \- The file system object.
|
||||
|
||||
**Return Value**
|
||||
|
||||
STATUS\_SUCCESS or error code.
|
||||
|
||||
**Discussion**
|
||||
|
||||
A file system that wishes to notify Windows about file changes must
|
||||
first issue an FspFileSystemBegin call, followed by 0 or more
|
||||
FspFileSystemNotify calls, followed by an FspFileSystemNotifyEnd call.
|
||||
|
||||
This operation allows any blocked file rename operations to proceed.
|
||||
|
||||
|
||||
</blockquote>
|
||||
</details>
|
||||
|
||||
@ -2613,7 +2865,7 @@ in a clean manner by calling this function.
|
||||
<br/>
|
||||
<p align="center">
|
||||
<sub>
|
||||
Copyright © 2015-2020 Bill Zissimopoulos
|
||||
Copyright © 2015-2021 Bill Zissimopoulos
|
||||
<br/>
|
||||
Generated with <a href="https://github.com/billziss-gh/prettydoc">prettydoc</a>
|
||||
</sub>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user