Função NtQueryInformationFile (ntifs.h)

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):

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.

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

Confira também

FILE_ACCESS_INFORMATION

FILE_ALIGNMENT_INFORMATION

FILE_ALL_INFORMATION

FILE_ATTRIBUTE_TAG_INFORMATION

FILE_BASIC_INFORMATION

FILE_EA_INFORMATION

FILE_INTERNAL_INFORMATION

FILE_IO_PRIORITY_HINT_INFORMATION

FILE_IS_REMOTE_DEVICE_INFORMATION

FILE_MODE_INFORMATION

FILE_NAME_INFORMATION

FILE_NETWORK_OPEN_INFORMATION

FILE_POSITION_INFORMATION

FILE_STANDARD_INFORMATION

Usando versões Nt e Zw das rotinas dos Serviços de Sistema Nativo

NtCreateFile

NtQueryInformationByName

NtSetInformationFile