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

Статья
12/21/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

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

Флаг	Значение
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)	Файловая система вернет сведения ОБ USN в 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 разрешить минифильтру получать сведения о файле во время создания файла, что позволяет избежать затрат на производительность последующего запроса, требующего обхода стека.

При предварительном создании минифильтр выполняет один вызов FltRequestFileInfoOnCreateComplet ion с сочетанием входных 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 в измененном типе информации.