FltRetrieveFileInfoOnCreateCompletionEx function (fltkernel.h)

Article
10/21/2021

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.

[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 );

// 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;

status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileStatInformation,
                                                  &fileStatSize,
                                                  &fileStatInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileLxInformation,
                                                  &fileLxSize,
                                                  &fileLxInfo );
status = FltRetrieveFileInfoOnCreateCompletionEx( Filter,
                                                  CallbackData,
                                                  QoCFileEaInformation, 
                                                  &fileEaSize, 
                                                  &fileEaInfo );

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