FltRetrieveFileInfoOnCreateCompletionEx function (fltkernel.h)
FltRetrieveFileInfoOnCreateCompletionEx queries for the specified file information upon file creation completion.
Syntax
NTSTATUS FLTAPI FltRetrieveFileInfoOnCreateCompletionEx(
[in] PFLT_FILTER Filter,
[in] PFLT_CALLBACK_DATA Data,
[in] ULONG InfoClass,
[out] PULONG RetInfoSize,
[out] PVOID *RetInfoBuffer
);
Parameters
[in] Filter
Opaque filter pointer that uniquely identifies the minifilter driver. It is returned by FltRegisterFilter, and remains constant as long as the minifilter driver is loaded.
[in] Data
Pointer to the FLT_CALLBACK_DATA callback data representing the I/O operation.
[in] InfoClass
Flag that indicates the type of file information to return. Note that flags cannot be combined. Can be one of the following values:
| Flag | Meaning |
|---|---|
| QoCFileStatInformation (0x00000001) | The file system will return file stat information in a QUERY_ON_CREATE_FILE_STAT_INFORMATION structure. |
| QoCFileLxInformation (0x00000002) | The file system will return extended Linux-like information in a QUERY_ON_CREATE_FILE_LX_INFORMATION structure. |
| QoCFileEaInformation (0x00000004) | The file system will return extended attributes (EA) in a QUERY_ON_CREATE_EA_INFORMATION structure. |
| QoCFileUsnInformation (0x00000008) | The file system will return USN information in a QUERY_ON_CREATE_USN_INFORMATION structure. |
| QoCFileSecurityInformation (0x00000010) | The file system will return file security information in a QUERY_ON_CREATE_SECURITY_INFORMATION structure. |
[out] RetInfoSize
Pointer to a ULONG that receives the size, in bytes, of the buffer that RetInfoBuffer points to.
[out] RetInfoBuffer
Receives a pointer to the requested InfoClass structure. If the file system is able to process the request but can't find the requested file information, this parameter is set to NULL.
Return value
| Return code | Description |
|---|---|
| STATUS_SUCCESS | The file system successfully returned the requested file information. |
| STATUS_NOT_FOUND | The file system processed the request, but the requested information was not present on the file, or the file system does not recognize the information request in InfoClass. The caller should not use traditional file system APIs to request the information. |
| STATUS_NOT_SUPPORTED | The file system was unable to retrieve the requested information. This error occurs when the file system doesn't support the information request or associated ECP, or because FltRequestFileInfoOnCreateCompletion wasn't called during file pre-creation. The caller should instead use traditional file system APIs to retry requesting the information. |
| STATUS_UNSUCCESSFUL | The file system received an error while trying to retrieve the requested information. The caller can try requesting the information by way of normal file system APIs, but that will likely fail. |
Remarks
FltRequestFileInfoOnCreateCompletion and FltRetrieveFileInfoOnCreateCompletionEx allow a minifilter to get information about a file during file create, thus avoiding the performance cost of a later query that would require a stack traversal.
- In pre-create, the minifilter makes one call to FltRequestFileInfoOnCreateCompletion with a combination of input InfoClassFlags that identify the requested information.
- The file system allocates the appropriate structure(s) and fills in the requested information, if supported, while it processes the create.
- In post-create, the minifilter calls FltRetrieveFileInfoOnCreateCompletionEx to get the information it requested in the pre-create call. If the minifilter requested more than one info type, it must call FltRetrieveFileInfoOnCreateCompletionEx once for each info type. For example:
// Pre-create:
NTSTATUS status;
status = FltRequestFileInfoOnCreateCompletion( Filter,
CallbackData,
QoCFileStatInformation
| QoCFileLxInformation
| QoCFileEaInformation
| QoCFileUsnInformation );
// Post-create:
NTSTATUS status;
ULONG fileStatSize, fileLxSize, fileEaSize;
QUERY_ON_CREATE_FILE_STAT_INFORMATION* fileStatInfo;
QUERY_ON_CREATE_FILE_LX_INFORMATION* fileLxInfo;
QUERY_ON_CREATE_EA_INFORMATION* fileEaInfo;
QUERY_ON_CREATE_USN_INFORMATION* fileUsnInfo;
QUERY_ON_CREATE_SECURITY_INFORMATION* fileSecurityInfo;
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
CallbackData,
QoCFileStatInformation,
&fileStatSize,
&fileStatInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
CallbackData,
QoCFileLxInformation,
&fileLxSize,
&fileLxInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
CallbackData,
QoCFileEaInformation,
&fileEaSize,
&fileEaInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
CallbackData,
QoCFileUsnInformation,
&fileUsnInfo,
&fileUsnInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
CallbackData,
QoCFileSecurityInformation,
&fileSecurityInfo,
&fileSecurityInfo);
Once FltRetrieveFileInfoOnCreateCompletionEx returns, a minifilter can write into the buffer that RetInfoBuffer points to. Any filters above that minifilter will see the changes if they call FltRetrieveFileInfoOnCreateCompletionEx on the modified information type.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10, version 1809 |
| Header | fltkernel.h |
See also
FltRequestFileInfoOnCreateCompletion
QUERY_ON_CREATE_EA_INFORMATION