Функция NtQueryInformationFile (ntifs.h)

Статья
02/07/2025

Подпрограмма NtQueryInformationFile возвращает различные виды сведений об объекте файла. См. также ntQueryInformationByName, что может быть более эффективно использовано для нескольких классов сведений о файлах.

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [in]  HANDLE                 FileHandle,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Параметры

[in] FileHandle

Обработка объекта файла. Дескриптор создается с помощью успешного вызова NtCreateFile или NtOpenFileили эквивалентного файла создания или открытия подпрограммы.

[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 сокращает количество запросов, необходимых для получения сведений о файле.
FileAlternateNameInformation (21)	Структура FILE_ALL_INFORMATION, в которой возвращаются сведения о альтернативном имени файла (его имя формата 8.3).
FileStreamInformation (22)	Буфер FILE_STREAM_INFORMATION структур, в которых перечисляются потоки данных файла или каталога.
FileCompressionInformation (28)	Структура FILE_COMPRESSION_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.
FileSfioReserveInformation (44)	Структура FILE_SFIO_RESERVE_INFORMATION.
FileHardLinkInformation (46)	Структура FILE_LINKS_INFORMATION.
FileNormalizedNameInformation (48)	Структура FILE_NAME_INFORMATION, в которой возвращается нормализованное имя файла.
FileIsRemoteDeviceInformation (51)	Структура FILE_IS_REMOTE_DEVICE_INFORMATION. Вызывающий объект может запрашивать эти сведения до тех пор, пока файл открыт, без каких-либо конкретных требований для DesiredAccess.
FileStandardLinkInformation (54)	Структура FILE_STANDARD_LINK_INFORMATION.
FileIdInformation (59)	Структура FILE_ID_INFORMATION.
FileDesiredStorageClassInformation (67)	Структура FILE_DESIRED_STORAGE_CLASS_INFORMATION.
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Структура FILE_CASE_SENSITIVE_INFORMATION. Вызывающий объект должен открыть файл с флагом FILE_READ_ATTRIBUTES, указанным в параметре DesiredAccess. Это значение доступно начиная с Windows 10 версии 1803.
FileStorageReserveIdInformation (74)	Структура FILE_STORAGE_RESERVE_ID_INFORMATION.
FileCaseSensitiveInformationForceAccessCheck (75)	Структура FILE_CASE_SENSITIVE_INFORMATION. Вызывающий объект должен открыть файл с флагом FILE_READ_ATTRIBUTES, указанным в параметре DesiredAccess. Это специальная версия операции FileCaseSensitiveInformation, которая используется для принудительного выполнения проверки доступа для драйвера режима ядра, аналогично проверкам, применяемым к вызывающей системе в пользовательском режиме. Эта операция распознается только ioManager, и файловая система никогда не должна получать ее. Это значение доступно начиная с Windows 10 версии 1803.
FileKnownFolderInformation (76)	Структура FILE_KNOWN_FOLDER_INFORMATION. Доступно начиная с Windows Server 2022.

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

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

Замечания

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

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

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

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

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

Заметка

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

Для вызовов драйверов в режиме ядра NtXxx и ZwXxx версии подпрограммы Windows Native System Services могут вести себя по-разному в том, как они обрабатывают и интерпретируют входные параметры. Дополнительные сведения о связи между NtXxx и ZwXxx версиями подпрограммы см. в разделе Using Nt and Zw Versions of the Native System Services Routines.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000.
целевая платформа	Всеобщий
заголовка	ntifs.h (включая Wdm.h, Ntddk.h, Ntifs.h)
библиотеки	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")
правил соответствия DDI	HwStorPortProhibitedDDIs, PowerIrpDDis