Функция FltRetrieveFileInfoOnCreateCompletionEx (fltkernel.h)

Статья
05/23/2024

FltRetrieveFileInfoOnCreateCompletionEx запрашивает указанные сведения о файле после завершения создания файла.

Синтаксис

NTSTATUS FLTAPI FltRetrieveFileInfoOnCreateCompletionEx(
  [in]  PFLT_FILTER        Filter,
  [in]  PFLT_CALLBACK_DATA Data,
  [in]  ULONG              InfoClass,
  [out] PULONG             RetInfoSize,
  [out] PVOID              *RetInfoBuffer
);

Параметры

[in] Filter

Указатель непрозрачного фильтра, который однозначно идентифицирует драйвер минифильтра. Он возвращается FltRegisterFilter и остается постоянным до тех пор, пока загружен драйвер мини-фильтра.

[in] Data

Указатель на FLT_CALLBACK_DATA данные обратного вызова, представляющие операцию ввода-вывода.

[in] InfoClass

Флаг, указывающий тип возвращаемых сведений о файле. Обратите внимание, что флаги нельзя объединять. Может иметь одно из следующих значений:

Flag	Значение
QoCFileStatInformation (0x00000001)	Файловая система вернет сведения о статистике файла в QUERY_ON_CREATE_FILE_STAT_INFORMATION структуре.
QoCFileLxInformation (0x00000002)	Файловая система будет возвращать расширенные сведения, подобные Linux, в QUERY_ON_CREATE_FILE_LX_INFORMATION структуре.
QoCFileEaInformation (0x00000004)	Файловая система вернет расширенные атрибуты (EA) в QUERY_ON_CREATE_EA_INFORMATION структуре.
QoCFileUsnInformation (0x00000008)	Файловая система вернет сведения о имени пользователя в QUERY_ON_CREATE_USN_INFORMATION структуре.
QoCFileSecurityInformation (0x00000010)	Файловая система возвращает сведения о безопасности файлов в QUERY_ON_CREATE_SECURITY_INFORMATION структуре.

[out] RetInfoSize

Указатель на ULONG, получающий размер буфера, на который указывает RetInfoBuffer , в байтах.

[out] RetInfoBuffer

Получает указатель на запрошенную структуру InfoClass . Если файловая система может обработать запрос, но не может найти запрошенные сведения о файле, этот параметр имеет значение NULL.

Возвращаемое значение

Код возврата	Описание
STATUS_SUCCESS	Файловая система успешно вернула запрошенные сведения о файле.
STATUS_NOT_FOUND	Файловая система обработала запрос, но запрошенная информация отсутствует в файле, или файловая система не распознает запрос информации в InfoClass. Вызывающий объект не должен использовать традиционные API файловой системы для запроса информации.
STATUS_NOT_SUPPORTED	Файловой системе не удалось получить запрошенные сведения. Эта ошибка возникает, когда файловая система не поддерживает запрос информации или связанный ECP, или потому, что fltRequestFileInfoOnCreateCompletion не был вызван во время предварительного создания файла. Вместо этого вызывающий объект должен использовать традиционные API файловой системы для повторного запроса информации.
STATUS_UNSUCCESSFUL	Файловая система получила сообщение об ошибке при попытке получить запрошенную информацию. Вызывающий объект может попытаться запросить сведения с помощью обычных API файловой системы, но это, скорее всего, завершится ошибкой.

FltRequestFileInfoOnCreateCompletion и FltRetrieveFileInfoOnCreateCompletionEx позволяют минифильтру получать сведения о файле во время создания файла, что позволяет избежать затрат на производительность последующего запроса, который потребует обхода стека.

При предварительном создании минифильтр выполняет один вызов FltRequestFileInfoOnCreateCompletion с сочетанием входных данных InfoClassFlags , которые идентифицируют запрошенные сведения.
Файловая система выделяет соответствующие структуры и заполняет запрошенные сведения, если они поддерживаются, во время обработки создания.
После создания мини-фильтр вызывает FltRetrieveFileInfoOnCreateCompletionEx , чтобы получить сведения, запрошенные в вызове перед созданием. Если минифильтр запросил несколько типов сведений, он должен вызывать FltRetrieveFileInfoOnCreateCompletionEx один раз для каждого типа сведений. Пример:


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

После того как FltRetrieveFileInfoOnCreateCompletionEx возвращается, минифильтр может записывать данные в буфер, на который указывает RetInfoBuffer . Все фильтры выше этого минифильтра будут видеть изменения, если они вызывают FltRetrieveFileInfoOnCreateCompletionEx для измененного типа информации.