Função NtQueryInformationFile (ntifs.h)

Artigo
07/11/2023

A rotina NtQueryInformationFile retorna vários tipos de informações sobre um objeto de arquivo. Consulte também NtQueryInformationByName, que pode ser usado com mais eficiência para algumas classes de informações de arquivo.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryInformationFile(
  [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 NtCreateFile ou NtOpenFile ou para uma rotina de criação ou abertura de arquivo equivalente.

[out] IoStatusBlock

Ponteiro para uma estrutura IO_STATUS_BLOCK que recebe a 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 (listados do valor de enumeração mais baixo para o mais alto):

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, não há garantia de que essa ID de arquivo seja 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 de nome de 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 . Ao combinar 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.
FileAlternateNameInformation (21)	Uma estrutura FILE_ALL_INFORMATION na qual retornar as informações de nome alternativo para um arquivo (seu nome de formato 8.3).
FileStreamInformation (22)	Um buffer de FILE_STREAM_INFORMATION estruturas nas quais enumerar os fluxos de dados de um arquivo ou diretório.
FileCompressionInformation (28)	Uma estrutura FILE_COMPRESSION_INFORMATION na qual retornar informações de compactação para 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 .
FileSfioReserveInformation (44)	Uma estrutura FILE_SFIO_RESERVE_INFORMATION .
FileHardLinkInformation (46)	Uma estrutura FILE_LINKS_INFORMATION .
FileNormalizedNameInformation (48)	Uma estrutura FILE_NAME_INFORMATION na qual retornar o nome normalizado de um arquivo.
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.
FileStandardLinkInformation (54)	Uma estrutura FILE_STANDARD_LINK_INFORMATION .
FileIdInformation (59)	Uma estrutura FILE_ID_INFORMATION .
FileDesiredStorageClassInformation (67)	Uma estrutura FILE_DESIRED_STORAGE_CLASS_INFORMATION .
FileStatInformation (68)	FILE_STAT_INFORMATION
FileStatLxInformation (70)	FILE_STAT_LX_INFORMATION
FileCaseSensitiveInformation (71)	Uma estrutura FILE_CASE_SENSITIVE_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_ATTRIBUTES especificado no parâmetro DesiredAccess . Esse valor está disponível a partir do Windows 10, versão 1803.
FileStorageReserveIdInformation (74)	Uma estrutura FILE_STORAGE_RESERVE_ID_INFORMATION .
FileCaseSensitiveInformationForceAccessCheck (75)	Uma estrutura FILE_CASE_SENSITIVE_INFORMATION . O chamador deve ter aberto o arquivo com o sinalizador FILE_READ_ATTRIBUTES especificado no parâmetro DesiredAccess . Esta é uma versão especial da operação FileCaseSensitiveInformation que é usada para forçar o IOManager a executar verificações de acesso para o driver do modo kernel, semelhante às verificações que se aplicam a um chamador no modo de usuário. Essa operação só é reconhecida pelo IOManager e um sistema de arquivos nunca deve recebê-la. Esse valor está disponível a partir do Windows 10, versão 1803.
FileKnownFolderInformation (76)	Uma estrutura FILE_KNOWN_FOLDER_INFORMATION . Disponível a partir do Windows Server 2022.

Retornar valor

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

Comentários

NtQueryInformationFile 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 NtCreateFile, NtQueryInformationFile retornará esse caminho completo.
Se o identificador ObjectAttributes-RootDirectory> foi aberto pelo nome em uma chamada para NtCreateFile e, posteriormente, o arquivo foi aberto por NtCreateFile em relação a esse identificador de diretório raiz, NtQueryInformationFile 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 NtCreateFile e, posteriormente, o arquivo foi aberto por NtCreateFile em relação a esse identificador de diretório raiz, NtQueryInformationFile retornará o caminho relativo.
No entanto, se o usuário tiver SeChangeNotifyPrivilege (descrito na documentação do SDK do Microsoft Windows), NtQueryInformationFile 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 NtQueryInformationFile 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 NtQueryInformationFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs de kernel especiais habilitadas.

Observação

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 Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000.
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclui Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
Regras de conformidade de DDI	HwStorPortProhibitedDIs, PowerIrpDDis