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

Статья
03/05/2024

Подпрограмма 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 проверок доступа для драйвера режима ядра, аналогично проверкам, которые применяются к вызывающей объекту пользовательского режима. Эта операция распознается только 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 (описано в документации по Microsoft Windows SDK), 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 и с включенными специальными APC ядра.

Примечание

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

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

Требования

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