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

Статья
02/07/2024

NtQueryInformationByName возвращает запрошенные сведения о файле, указанном по имени файла.

Синтаксис

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationByName(
  [in]  POBJECT_ATTRIBUTES     ObjectAttributes,
  [out] PIO_STATUS_BLOCK       IoStatusBlock,
  [out] PVOID                  FileInformation,
  [in]  ULONG                  Length,
  [in]  FILE_INFORMATION_CLASS FileInformationClass
);

Параметры

[in] ObjectAttributes

Указатель на структуру OBJECT_ATTRIBUTES , содержащую атрибуты файла, включая имя файла.

[out] IoStatusBlock

Указатель на структуру IO_STATUS_BLOCK , содержащую состояние ввода-вывода вызывающего объекта.

[out] FileInformation

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

[in] Length

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

[in] FileInformationClass

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

Значение FILE_INFORMATION_CLASS	Тип возвращаемых сведений
FileStatInformation (68)	FILE_STAT_INFORMATION. Доступно начиная с Windows 10 версии 1709.
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION. Доступно начиная с Windows 10 обновления за апрель 2018 г.
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION. Доступно начиная с Windows 10 обновления за апрель 2018 г.
FileStatBasicInformation (77)	FILE_STAT_BASIC_INFORMATION. Доступно начиная с Windows 11 сборки 26048.

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

NtQueryInformationByName возвращает STATUS_SUCCESS после успешного завершения; В противном случае возвращается код ошибки, например один из следующих.

Код ошибки	Значение
STATUS_INVALID_PARAMETER	Параметр FileInformationClass содержит недопустимое значение.
STATUS_INFO_LENGTH_MISMATCH	Размер буфера, указанный параметром Length , недостаточно велик, чтобы содержать запрошенные сведения.

NtQueryInformationByName запрашивает и возвращает запрошенные сведения о файле. Это делается без открытия фактического файла, что делает его более эффективным, чем NtQueryInformationFile, который требует открытия файла (и последующего закрытия файла).

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 10 версии 1703
Верхняя часть	ntifs.h
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (см. раздел "Примечания")