Função ZwQueryInformationFile (wdm.h)

Artigo
08/08/2023

A rotina ZwQueryInformationFile retorna vários tipos de informações sobre um objeto de arquivo.

Sintaxe

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

Parâmetros

[in] FileHandle

Manipule para um objeto de arquivo. O identificador é criado por uma chamada bem-sucedida para ZwCreateFile ou ZwOpenFile.

[out] IoStatusBlock

Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação. O membro Information recebe o número de bytes que essa rotina realmente grava no buffer FileInformation .

[out] FileInformation

Ponteiro para um buffer alocado pelo chamador no qual a rotina grava as informações solicitadas sobre o objeto de arquivo. O parâmetro FileInformationClass especifica o tipo de informação que o chamador solicita.

[in] Length

O tamanho, em bytes, do buffer apontado por FileInformation.

[in] FileInformationClass

Especifica o tipo de informação a ser retornado sobre o arquivo, no buffer para o qual FileInformation aponta. Os drivers intermediários e de dispositivo podem especificar qualquer um dos seguintes valores de FILE_INFORMATION_CLASS .

FILE_INFORMATION_CLASS valor	Tipo de informação retornada
FileBasicInformation (4)	Uma estrutura FILE_BASIC_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_ATTRIBUTES especificado no parâmetro DesiredAccess .
FileStandardInformation (5)	Uma estrutura FILE_STANDARD_INFORMATION . O chamador pode consultar essas informações desde que o arquivo esteja aberto, sem nenhum requisito específico para DesiredAccess.
FileInternalInformation (6)	Uma estrutura FILE_INTERNAL_INFORMATION . Essa estrutura especifica uma ID de arquivo de 64 bits que identifica exclusivamente um arquivo no NTFS. Em outros sistemas de arquivos, essa ID de arquivo não tem garantia de ser exclusiva.
FileEaInformation (7)	Uma estrutura FILE_EA_INFORMATION . Essa estrutura especifica o tamanho do bloco de atributos estendidos associado ao arquivo.
FileAccessInformation (8)	Uma estrutura FILE_ACCESS_INFORMATION . Essa estrutura contém uma máscara de acesso. Para obter mais informações sobre máscaras de acesso, consulte ACCESS_MASK.
FileNameInformation (9)	Uma estrutura FILE_NAME_INFORMATION . A estrutura pode conter o caminho completo do arquivo ou apenas uma parte dele. O chamador pode consultar essas informações desde que o arquivo esteja aberto, sem nenhum requisito específico para DesiredAccess. Para obter mais informações sobre a sintaxe nome do arquivo, consulte a seção Comentários mais adiante neste tópico.
FilePositionInformation (14)	Uma estrutura FILE_POSITION_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador DesiredAccess FILE_READ_DATA ou FILE_WRITE_DATA especificado no parâmetro DesiredAccess e com o sinalizador FILE_SYNCHRONOUS_IO_ALERT ou FILE_SYNCHRONOUS_IO_NONALERT especificado no parâmetro CreateOptions .
FileModeInformation (16)	Uma estrutura FILE_MODE_INFORMATION . Essa estrutura contém um conjunto de sinalizadores que especificam o modo no qual o arquivo pode ser acessado. Esses sinalizadores são um subconjunto das opções que podem ser especificadas no parâmetro CreateOptions da rotina IoCreateFile .
FileAlignmentInformation (17)	Uma estrutura FILE_ALIGNMENT_INFORMATION . O chamador pode consultar essas informações desde que o arquivo esteja aberto, sem nenhum requisito específico para DesiredAccess[. Essas informações serão úteis se o arquivo tiver sido aberto com o sinalizador FILE_NO_INTERMEDIATE_BUFFERING especificado no parâmetro CreateOptions** .
FileAllInformation (18)	Uma estrutura FILE_ALL_INFORMATION . Combinando várias estruturas de informações de arquivo em uma única estrutura, FILE_ALL_INFORMATION reduz o número de consultas necessárias para obter informações sobre um arquivo.
FileNetworkOpenInformation (34)	Uma estrutura FILE_NETWORK_OPEN_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_ATTRIBUTES especificado no parâmetro DesiredAccess .
FileAttributeTagInformation (35)	Uma estrutura FILE_ATTRIBUTE_TAG_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_ATTRIBUTES especificado no parâmetro DesiredAccess .
FileIoPriorityHintInformation (43)	Uma estrutura FILE_IO_PRIORITY_HINT_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_DATA especificado no parâmetro DesiredAccess .
FileIsRemoteDeviceInformation (51)	Uma estrutura FILE_IS_REMOTE_DEVICE_INFORMATION . O chamador pode consultar essas informações desde que o arquivo esteja aberto, sem nenhum requisito específico para DesiredAccess.
FileKnownFolderInformation (76)	Uma estrutura FILE_KNOWN_FOLDER_INFORMATION . Disponível a partir do Windows Server 2022.

Retornar valor

ZwQueryInformationFile retorna STATUS_SUCCESS ou um código de erro NTSTATUS apropriado.

Comentários

ZwQueryInformationFile retorna informações sobre o objeto de arquivo especificado. Observe que ele retorna zero em qualquer membro de uma estrutura FILE_XXX_INFORMATION que não é compatível com um dispositivo ou sistema de arquivos específico.

Quando FileInformationClass = FileNameInformation, o nome do arquivo é retornado na estrutura FILE_NAME_INFORMATION . A sintaxe precisa do nome do arquivo depende de vários fatores:

Se você abriu o arquivo enviando um caminho completo para ZwCreateFile, ZwQueryInformationFile retornará esse caminho completo.
Se o identificador ObjectAttributes-RootDirectory> foi aberto pelo nome em uma chamada para ZwCreateFile e, posteriormente, o arquivo foi aberto por ZwCreateFile em relação a esse identificador de diretório raiz, ZwQueryInformationFile retornará o caminho completo.
Se o identificador ObjectAttributes-RootDirectory> foi aberto pela ID do arquivo (usando o sinalizador FILE_OPEN_BY_FILE_ID) em uma chamada para ZwCreateFile e, posteriormente, o arquivo foi aberto por ZwCreateFile em relação a esse identificador de diretório raiz, ZwQueryInformationFile retornará o caminho relativo.
No entanto, se o usuário tiver SeChangeNotifyPrivilege, ZwQueryInformationFile retornará o caminho completo em todos os casos.
Se apenas o caminho relativo for retornado, a cadeia de caracteres de nome de arquivo não começará com uma barra invertida.
Se o caminho completo e o nome do arquivo forem retornados, a cadeia de caracteres começará com uma única barra invertida, independentemente de sua localização. Assim, o arquivo C:\dir1\dir2\filename.ext aparecerá como \dir1\dir2\filename.ext, enquanto o arquivo \server\share\dir1\dir2\filename.ext aparecerá como \server\share\dir1\dir2\filename.ext.

Se ZwQueryInformationFile falhar devido a um estouro de buffer, os drivers que implementam FileNameInformation deverão retornar quantos caracteres WCHAR do nome do arquivo caberão no buffer e especificar o comprimento completo necessário no parâmetro FileNameLength da estrutura FILE_NAME_INFORMATION . Você deve reemissar a consulta usando o tamanho do nome do arquivo para que possa recuperar o nome completo do arquivo. Os drivers que não seguem esse padrão podem exigir um aumento gradual de comprimento até recuperarem o nome completo do arquivo. Para obter mais informações sobre como trabalhar com arquivos, consulte Usando arquivos em um driver.

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

Se a chamada para essa função ocorrer no modo de usuário, você deverá usar o nome "NtQueryInformationFile" em vez de "ZwQueryInformationFile".

Para chamadas de drivers no modo kernel, as versões NtXxx e ZwXxx de uma rotina dos Serviços do Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx**** e ZwXxx**** de uma rotina, consulte Using Nt and Zw Versions of the Native System Services Routines.

Requisitos

Requisito	Valor
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)