Função NtQueryInformationByName (ntifs.h)

Artigo
02/03/2024

NtQueryInformationByName retorna as informações solicitadas sobre um arquivo especificado pelo nome do arquivo.

Sintaxe

__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
);

Parâmetros

[in] ObjectAttributes

Ponteiro para uma estrutura OBJECT_ATTRIBUTES que contém os atributos do arquivo, incluindo o nome do arquivo.

[out] IoStatusBlock

Ponteiro uma estrutura de IO_STATUS_BLOCK que contém a status de E/S do chamador.

[out] FileInformation

Ponteiro para o buffer fornecido pelo chamador no qual retornar as informações solicitadas sobre o arquivo. A estrutura do buffer é determinada pelo parâmetro FileInformationClass .

[in] Length

Comprimento, em bytes, do buffer para o qual FileInformation aponta.

[in] FileInformationClass

Um valor FILE_INFORMATION_CLASS que identifica o tipo de informações de arquivo a serem retornadas no buffer para o qual FileInformation aponta. FileInformationClass pode ser um dos valores a seguir.

Valor FILE_INFORMATION_CLASS	Tipo de informações a serem retornadas
FileStatInformation (68)	FILE_STAT_INFORMATION. Disponível a partir do Windows 10, versão 1709.
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION. Disponível a partir do Windows 10 Atualização de abril de 2018.
FileCaseSensitiveInformation (71)	FILE_CASE_SENSITIVE_INFORMATION. Disponível a partir do Windows 10 Atualização de abril de 2018.
FileStatBasicInformation (77)	FILE_STAT_BASIC_INFORMATION. Disponível a partir do Windows 11, build 26048.

Retornar valor

NtQueryInformationByName retorna STATUS_SUCCESS após a conclusão bem-sucedida; caso contrário, retornará um código de erro, como um dos seguintes.

Código do Erro	Significado
STATUS_INVALID_PARAMETER	O parâmetro FileInformationClass contém um valor inválido.
STATUS_INFO_LENGTH_MISMATCH	O tamanho do buffer especificado por Length não é grande o suficiente para conter as informações solicitadas.

Comentários

NtQueryInformationByName consulta e retorna as informações solicitadas sobre o arquivo. Ele faz isso sem abrir o arquivo real, tornando-o mais eficiente do que NtQueryInformationFile, que requer um arquivo aberto (e fechamento de arquivo subsequente).

Os chamadores de NtQueryInformationByName devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 1703
Cabeçalho	ntifs.h
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)