Функция ZwQueryInformationFile (wdm.h)

Статья
08/08/2023

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

Синтаксис

NTSYSAPI NTSTATUS ZwQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Параметры

[in] FileHandle

Дескриптор объекта файла. Дескриптор создается путем успешного вызова ZwCreateFile или ZwOpenFile.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , которая получает окончательное состояние завершения и сведения об операции. Элемент Information получает количество байтов, которое эта подпрограмма фактически записывает в буфер FileInformation .

[out] FileInformation

Указатель на буфер, выделенный вызывающим объектом, в который подпрограмма записывает запрошенные сведения об объекте файла. Параметр FileInformationClass указывает тип сведений, которые запрашивает вызывающий объект.

[in] Length

Размер (в байтах) буфера, на который указывает FileInformation.

[in] FileInformationClass

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

значение FILE_INFORMATION_CLASS	Тип возвращаемых сведений
FileBasicInformation (4)	Структура FILE_BASIC_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_READ_ATTRIBUTES, указанным в параметре DesiredAccess .
FileStandardInformation (5)	Структура FILE_STANDARD_INFORMATION . Вызывающий объект может запрашивать эти сведения, пока файл открыт, без каких-либо особых требований к DesiredAccess.
FileInternalInformation (6)	Структура FILE_INTERNAL_INFORMATION . Эта структура задает идентификатор 64-разрядного файла, который однозначно идентифицирует файл в NTFS. В других файловой системе этот идентификатор файла не гарантируется как уникальный.
FileEaInformation (7)	Структура FILE_EA_INFORMATION . Эта структура определяет размер блока расширенных атрибутов, связанного с файлом.
FileAccessInformation (8)	Структура FILE_ACCESS_INFORMATION . Эта структура содержит маску доступа. Дополнительные сведения о масках доступа см. в разделе ACCESS_MASK.
FileNameInformation (9)	Структура FILE_NAME_INFORMATION . Структура может содержать полный путь к файлу или только его часть. Вызывающий объект может запрашивать эти сведения, пока файл открыт, без каких-либо особых требований к DesiredAccess. Дополнительные сведения о синтаксисе имени файла см. в разделе Примечания далее в этом разделе.
FilePositionInformation (14)	Структура FILE_POSITION_INFORMATION . Вызывающий объект должен открыть файл с флагом DesiredAccess FILE_READ_DATA или FILE_WRITE_DATA, указанным в параметре DesiredAccess , и флагом FILE_SYNCHRONOUS_IO_ALERT или FILE_SYNCHRONOUS_IO_NONALERT, указанным в параметре CreateOptions .
FileModeInformation (16)	Структура FILE_MODE_INFORMATION . Эта структура содержит набор флагов, указывающих режим, в котором можно получить доступ к файлу. Эти флаги представляют собой подмножество параметров, которые можно указать в параметре CreateOptions подпрограммыIoCreateFile .
FileAlignmentInformation (17)	Структура FILE_ALIGNMENT_INFORMATION . Вызывающий объект может запрашивать эти сведения, пока файл открыт, без каких-либо особых требований к DesiredAccess[. Эти сведения полезны, если файл был открыт с флагом FILE_NO_INTERMEDIATE_BUFFERING, указанным в параметре CreateOptions** .
FileAllInformation (18)	Структура FILE_ALL_INFORMATION . Объединяя несколько структур сведений о файлах в одну структуру, FILE_ALL_INFORMATION сокращает количество запросов, необходимых для получения сведений о файле.
FileNetworkOpenInformation (34)	Структура FILE_NETWORK_OPEN_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_READ_ATTRIBUTES, указанным в параметре DesiredAccess .
FileAttributeTagInformation (35)	Структура FILE_ATTRIBUTE_TAG_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_READ_ATTRIBUTES, указанным в параметре DesiredAccess .
FileIoPriorityHintInformation (43)	Структура FILE_IO_PRIORITY_HINT_INFORMATION . Вызывающий объект должен открыть файл с флагом FILE_READ_DATA, указанным в параметре DesiredAccess .
FileIsRemoteDeviceInformation (51)	Структура FILE_IS_REMOTE_DEVICE_INFORMATION . Вызывающий объект может запрашивать эти сведения, пока файл открыт, без каких-либо особых требований к DesiredAccess.
FileKnownFolderInformation (76)	Структура FILE_KNOWN_FOLDER_INFORMATION . Доступно начиная с Windows Server 2022.

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

ZwQueryInformationFile возвращает STATUS_SUCCESS или соответствующий код ошибки NTSTATUS.

ZwQueryInformationFile возвращает сведения об указанном объекте файла. Обратите внимание, что он возвращает ноль в любом элементе структуры FILE_XXX_INFORMATION , которая не поддерживается определенным устройством или файловой системой.

При fileInformationClass = FileNameInformation имя файла возвращается в структуре FILE_NAME_INFORMATION . Точный синтаксис имени файла зависит от ряда факторов:

Если вы открыли файл, отправив полный путь к ZwCreateFile, ZwQueryInformationFile возвращает этот полный путь.
Если дескриптор ObjectAttributes-RootDirectory> был открыт по имени в вызове ZwCreateFile, а затем файл был открыт ZwCreateFile относительно этого дескриптора корневого каталога, ZwQueryInformationFile возвращает полный путь.
Если дескриптор ObjectAttributes-RootDirectory> был открыт идентификатором файла (с помощью флага FILE_OPEN_BY_FILE_ID) в вызове ZwCreateFile, а затем файл был открыт ZwCreateFile относительно этого дескриптора корневого каталога, ZwQueryInformationFile возвращает относительный путь.
Однако если у пользователя есть SeChangeNotifyPrivilege, ZwQueryInformationFile во всех случаях возвращает полный путь.
Если возвращается только относительный путь, строка имени файла не будет начинаться с обратной косой черты.
Если возвращаются полный путь и имя файла, строка будет начинаться с одной обратной косой черты, независимо от ее расположения. Таким образом, файл C:\dir1\dir2\filename.ext будет отображаться как \dir1\dir2\filename.ext, а файл \server\share\dir1\dir2\filename.ext будет отображаться как \server\share\dir1\dir2\filename.ext.

Если ZwQueryInformationFile завершается сбоем из-за переполнения буфера, драйверы, реализующие FileNameInformation , должны вернуть столько символов WCHAR имени файла, сколько поместится в буфере, и указать полную длину, необходимую в параметре FileNameLengthструктуры FILE_NAME_INFORMATION . Вы должны повторно выполнить запрос, используя длину имени файла, чтобы можно было получить полное имя файла. Драйверы, которые не следуют этому шаблону, могут требовать постепенного увеличения длины до тех пор, пока они не получите полное имя файла. Дополнительные сведения о работе с файлами см. в разделе Использование файлов в драйвере.

Вызывающие файлы ZwQueryInformationFile должны выполняться по адресу IRQL = PASSIVE_LEVEL и с включенными специальными APC ядра.

Если вызов этой функции происходит в пользовательском режиме, следует использовать имя NtQueryInformationFile вместо ZwQueryInformationFile.

Для вызовов из драйверов режима ядра версии NtXxx и ZwXxx подпрограммы собственных системных служб Windows могут вести себя по-разному, так как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между версиями процедуры NtXxx**** и ZwXxx**** см. в разделе Использование версий Nt и Zw собственных процедур системных служб.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)