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

Статья
08/07/2023

Подпрограмма FltGetFileNameInformationUnsafe возвращает сведения об имени для открытого файла или каталога.

Синтаксис

NTSTATUS FLTAPI FltGetFileNameInformationUnsafe(
  [in]           PFILE_OBJECT               FileObject,
  [in, optional] PFLT_INSTANCE              Instance,
  [in]           FLT_FILE_NAME_OPTIONS      NameOptions,
  [out]          PFLT_FILE_NAME_INFORMATION *FileNameInformation
);

Параметры

[in] FileObject

Указатель на объект файла для файла или каталога. Объект файла должен быть открыт в данный момент. Этот параметр является обязательным и не может иметь значение NULL.

[in, optional] Instance

Указатель экземпляра для вызывающего объекта. Для этого параметра можно задать значение NULL.

[in] NameOptions

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

В следующей таблице описаны значения флагов формата имен. Можно указать только один из флагов. Дополнительные сведения об этих форматах см. в разделе FLT_FILE_NAME_INFORMATION.

Значение	Значение
FLT_FILE_NAME_NORMALIZED	Параметр FileNameInformation получает адрес структуры, содержащей нормализованное имя файла.
FLT_FILE_NAME_OPENED	Параметр FileNameInformation получает адрес структуры, содержащей имя, которое использовалось при открытии файла.
FLT_FILE_NAME_SHORT	Параметр FileNameInformation получает адрес структуры, содержащей короткое (8.3) имя файла. Короткое имя состоит из 8 символов, за которым сразу же следует точка и еще до 3 символов. Краткое имя файла не включает имя тома, путь к каталогу или имя потока.

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

Значение	Значение
FLT_FILE_NAME_QUERY_DEFAULT	FltGetFileNameInformationUnsafe запрашивает в кэше имен диспетчера фильтров сведения об имени файла. Если имя не найдено в кэше, FltGetFileNameInformationUnsafe запрашивает файловую систему и кэширует результат.
FLT_FILE_NAME_QUERY_CACHE_ONLY	FltGetFileNameInformationUnsafe запрашивает в кэше имен диспетчера фильтров сведения об имени файла. FltGetFileNameInformationUnsafe не запрашивает файловую систему.
FLT_FILE_NAME_QUERY_FILESYSTEM_ONLY	FltGetFileNameInformationUnsafe запрашивает у файловой системы сведения об имени файла. FltGetFileNameInformationUnsafe не запрашивает кэш имен диспетчера фильтров и не кэширует результаты запроса файловой системы.
FLT_FILE_NAME_QUERY_ALWAYS_ALLOW_CACHE_LOOKUP	FltGetFileNameInformationUnsafe запрашивает в кэше имен диспетчера фильтров сведения об имени файла. Если имя не найдено в кэше и в настоящее время это безопасно, FltGetFileNameInformationUnsafe запрашивает в файловой системе сведения об имени файла и кэширует результат.

[out] FileNameInformation

Указатель на переменную, выделенную вызывающим объектом, которая получает адрес структуры, выделенной системой FLT_FILE_NAME_INFORMATION. FltGetFileNameInformationUnsafe выделяет эту структуру из выгружаемого пула. Если эти сведения больше не нужны, вызывающий объект должен освободить структуру, вызвав FltReleaseFileNameInformation. Этот параметр является обязательным и не может иметь значение NULL.

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

FltGetFileNameInformationUnsafe возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например одно из следующих значений:

Код возврата	Описание
STATUS_FLT_INVALID_NAME_REQUEST	Объект файла, на который указывает параметр FileObject , в настоящее время не открыт. Это код ошибки.
STATUS_INVALID_PARAMETER	Передано недопустимое значение для параметра FileNameInformation . Это код ошибки.

Подпрограмма FltGetFileNameInformationUnsafe предоставляется, чтобы можно было запросить имя файлового объекта вне контекста операции ввода-вывода для этого объекта файла; В противном случае необходимо вызвать FltGetFileNameInformation.

В отличие от процедуры FltGetFileNameInformation , FltGetFileNameInformationUnsafe не защищает вызывающий объект от следующих типов обстоятельств, когда запрос к файловой системе сведений об имени может привести к взаимоблокировке для методов запроса, отличных от FLT_FILE_NAME_QUERY_CACHE_ONLY:

В пути ввода-вывода подкачки.
Если поле TopLevelIrp текущего потока не равно NULL. Дополнительные сведения см. в разделе IoGetTopLevelIrp.
После завершения операции IRP_MJ_CLEANUP ; то есть в пути после очистки, перед закрытием или после закрытия (для целевого объекта файла установлен флаг FO_CLEANUP_COMPLETE).
В процедуре обратного вызова перед операцией (PFLT_PRE_OPERATION_CALLBACK) или после операции (PFLT_POST_OPERATION_CALLBACK) для любой из следующих операций:
- IRP_MJ_ACQUIRE_FOR_CC_FLUSH
- IRP_MJ_ACQUIRE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_CC_FLUSH
- IRP_MJ_RELEASE_FOR_MOD_WRITE
- IRP_MJ_RELEASE_FOR_SECTION_SYNCHRONIZATION
В процедуре обратного вызова после операции для IRP_MJ_ACQUIRE_FOR_SECTION_SYNCHRONIZATION.
Если все ПТР отключены; то есть, когда KeAreAllApcsDisabled возвращает значение TRUE.

Для Windows Vista или Server 2008 и более поздних версий, если у минифильтра еще нет экземпляра фильтра, например в подпрограмме DriverEntry , он может использовать NULL для параметра Instance . Это позволяет подпрограммам DriverEntry получать доступ к сведениям об имени файла. За исключением этого случая, NULL значение параметра экземпляра зарезервировано для системного использования.

В операциях создания, жесткого связывания и переименования туннелирование имен файлов может сделать недействительным окончательный компонент в нормализованном имени файла, который драйвер минифильтра получает в подпрограмме обратного вызова перед операцией. Если драйвер минифильтра получает нормализованные сведения об имени файла в процедуре обратного вызова перед операции (PFLT_PRE_OPERATION_CALLBACK), вызывая подпрограмму , например FltGetFileNameInformationUnsafe, он должен вызвать FltGetTunneledName из подпрограммы обратного вызова после операции (PFLT_POST_OPERATION_CALLBACK), чтобы получить правильные сведения об имени файла.

Дополнительные сведения о нормализованных имени файлах см. в разделе FLT_FILE_NAME_INFORMATION.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL (см. примечания)