Função NtQueryDirectoryFileEx (ntifs.h)

Artigo
08/07/2023

A rotina NtQueryDirectoryFileEx retorna vários tipos de informações sobre arquivos no diretório especificado por um determinado identificador de arquivo.

Sintaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFileEx(
  [in]           HANDLE                 FileHandle,
  [in, optional] HANDLE                 Event,
  [in, optional] PIO_APC_ROUTINE        ApcRoutine,
  [in, optional] PVOID                  ApcContext,
  [out]          PIO_STATUS_BLOCK       IoStatusBlock,
  [out]          PVOID                  FileInformation,
  [in]           ULONG                  Length,
                 FILE_INFORMATION_CLASS FileInformationClass,
  [in]           ULONG                  QueryFlags,
  [in, optional] PUNICODE_STRING        FileName
);

Parâmetros

[in] FileHandle

Um identificador retornado por NtCreateFile ou NtOpenFile para o objeto de arquivo que representa o diretório para o qual as informações estão sendo solicitadas. O objeto de arquivo deve ter sido aberto para E/S assíncrona se o chamador especificar um valor não NULL para Event ou ApcRoutine.

[in, optional] Event

Um identificador opcional para um evento criado pelo chamador. Se esse parâmetro for fornecido, o chamador será colocado em um estado de espera até que a operação solicitada seja concluída e o evento fornecido seja definido como o estado Sinalizado. Esse parâmetro é opcional e pode ser NULL. Ele deve ser NULL se o chamador aguardar que o FileHandle seja definido como o estado Sinalizado.

[in, optional] ApcRoutine

Um endereço de uma rotina de APC opcional fornecida pelo chamador a ser chamada quando a operação solicitada for concluída. Esse parâmetro é opcional e pode ser NULL. Se houver um objeto de conclusão de E/S associado ao objeto de arquivo, esse parâmetro deverá ser NULL.

[in, optional] ApcContext

Um ponteiro opcional para uma área de contexto determinada pelo chamador se o chamador fornecer um APC ou se um objeto de conclusão de E/S estiver associado ao objeto de arquivo. Quando a operação for concluída, esse contexto será passado para o APC, se um tiver sido especificado ou incluído como parte da mensagem de conclusão que o Gerenciador de E/S posta no objeto de conclusão de E/S associado.

Esse parâmetro é opcional e pode ser NULL. Ele deverá ser NULL se ApcRoutine for NULL e não houver nenhum objeto de conclusão de E/S associado ao objeto de arquivo.

[out] IoStatusBlock

Um ponteiro para uma estrutura IO_STATUS_BLOCK que recebe o status de conclusão final e informações sobre a operação. Para chamadas bem-sucedidas que retornam dados, o número de bytes gravados no buffer FileInformation é retornado no membro Informações da estrutura.

[out] FileInformation

Um ponteiro para um buffer de saída que recebe as informações desejadas sobre o arquivo. A estrutura das informações retornadas no buffer é definida pelo parâmetro FileInformationClass .

[in] Length

O tamanho, em bytes, do buffer apontado por FileInformation. O chamador deve definir esse parâmetro de acordo com o FileInformationClass especificado.

FileInformationClass

O tipo de informação a ser retornada sobre arquivos no diretório. Tipo de informação a ser retornada sobre arquivos no diretório. FileInformationClass pode ser um dos valores de FILE_INFORMATION_CLASS a seguir.

Valor	Significado
FileDirectoryInformation (1)	Retornar uma estrutura de FILE_DIRECTORY_INFORMATION para cada arquivo.
FileFullDirectoryInformation (2)	Retornar uma estrutura de FILE_FULL_DIR_INFORMATION para cada arquivo.
FileBothDirectoryInformation (3)	Retornar uma estrutura de FILE_BOTH_DIR_INFORMATION para cada arquivo.
FileNamesInformation (12)	Retornar uma estrutura de FILE_NAMES_INFORMATION para cada arquivo.
FileObjectIdInformation (29)	Retornar uma estrutura FILE_OBJECTID_INFORMATION para cada arquivo que tenha uma ID de objeto no volume. Essa classe de informações é válida apenas para o diretório especial "\$Extend\$ObjId:$O:$INDEX_ALLOCATION" em volumes NTFS.
FileQuotaInformation (32)	Retornar uma única estrutura de FILE_QUOTA_INFORMATION para cada usuário no volume que tem cotas aplicadas. Essa classe de informação é válida apenas para o diretório especial "\$Extend\$Quota:$Q:$INDEX_ALLOCATION" em volumes NTFS.
FileReparsePointInformation (33)	Retornar uma única estrutura de FILE_REPARSE_POINT_INFORMATION para cada arquivo que tem um ponto de nova análise no volume. Essa classe de informação é válida apenas para o diretório especial "\$Extend\$Reparse:$R:$INDEX_ALLOCATION" em volumes NTFS e ReFS.
FileIdBothDirectoryInformation (37)	Retornar uma estrutura FILE_ID_BOTH_DIR_INFORMATION para cada arquivo.
FileIdFullDirectoryInformation (38)	Retornar uma estrutura de FILE_ID_FULL_DIR_INFORMATION para cada arquivo.
FileIdGlobalTxDirectoryInformation (50)	Retornar uma estrutura FILE_ID_GLOBAL_TX_DIR_INFORMATION para cada arquivo.
FileIdExtdDirectoryInformation (60)	Retornar uma estrutura FILE_ID_EXTD_DIR_INFORMATION para cada arquivo.
FileIdExtdBothDirectoryInformation (63)	Retornar uma estrutura de FILE_ID_EXTD_BOTH_DIR_INFORMATION para cada arquivo.

[in] QueryFlags

Um ou mais dos sinalizadores contidos em SL_QUERY_DIRECTORY_MASK. Os valores possíveis são especificados na tabela a seguir.

Valor	Significado
SL_RESTART_SCAN (0x00000001)	A verificação será iniciada na primeira entrada do diretório. Se esse sinalizador não estiver definido, a verificação será retomada de onde a última consulta terminou.
SL_RETURN_SINGLE_ENTRY (0x00000002)	Normalmente, o buffer de retorno é empacotado com tantas entradas de diretório correspondentes que se encaixam. Se esse sinalizador estiver definido, o sistema de arquivos retornará apenas uma entrada de diretório por vez. Isso torna a operação menos eficiente.
SL_INDEX_SPECIFIED (0x00000004)	A verificação deve começar em uma posição indexada especificada no diretório. Esse sinalizador só poderá ser definido se você gerar sua própria IRP_MJ_DIRECTORY_CONTROL IRP; o índice é especificado no IRP. A forma como a posição é especificada varia de sistema de arquivos para sistema de arquivos.
SL_RETURN_ON_DISK_ENTRIES_ONLY (0x00000008)	Todos os filtros do sistema de arquivos que executam a virtualização de diretório ou a expansão just-in-time devem simplesmente passar a solicitação para o sistema de arquivos e retornar entradas que estão atualmente em disco. Nem todos os sistemas de arquivos dão suporte a esse sinalizador.
SL_NO_CURSOR_UPDATE_QUERY (0x00000010)	Os sistemas de arquivos mantêm informações de cursor de diretório por FileObject. Quando vários threads fazem consultas usando o mesmo FileObject, o acesso à estrutura por FileObject é threaded único para evitar a corrupção do estado do cursor. Esse sinalizador instrui o sistema de arquivos a não atualizar informações de estado do cursor por FileObject, permitindo que vários threads consultem em paralelo usando o mesmo identificador. Ele se comporta como se SL_RESTART_SCAN fosse especificado em cada chamada. Se um padrão de cartão selvagem for fornecido na próxima chamada, a operação não retomará onde a última consulta terminou. Isso permite o verdadeiro suporte à consulta de diretório assíncrono. Se esse sinalizador for usado dentro de uma transação TxF, a operação falhará. Nem todos os sistemas de arquivos dão suporte a esse sinalizador.

[in, optional] FileName

Um ponteiro opcional para uma cadeia de caracteres Unicode alocada pelo chamador que contém o nome de um arquivo (ou vários arquivos, se curingas forem usados) no diretório especificado por FileHandle. Esse parâmetro é opcional:

Se FileName não for NULL, somente os arquivos cujos nomes correspondem à cadeia de caracteres FileName serão incluídos na verificação de diretório.
Se FileName for NULL:
- Se SL_RETURN_SINGLE_ENTRY não estiver definido em QueryFlags, todos os arquivos serão incluídos.
- Se SL_RETURN_SINGLE_ENTRY estiver definido, apenas um arquivo será incluído.

O FileName é usado como uma expressão de pesquisa e é capturado na primeira chamada para NtQueryDirectoryFileEx para um determinado identificador. As chamadas subsequentes para NtQueryDirectoryFileEx usarão a expressão de pesquisa definida na primeira chamada. O parâmetro FileName passado para chamadas subsequentes será ignorado.

Retornar valor

NtQueryDirectoryFileEx retorna STATUS_SUCCESS ou um erro apropriado status. O conjunto de erros status valores que podem ser retornados é específico do sistema de arquivos. NtQueryDirectoryFileEx também retorna o número de bytes realmente gravados no buffer FileInformation fornecido no membro Information de IoStatusBlock. Alguns possíveis códigos de erro e motivos podem ser os seguintes:

Código de retorno	Significado
STATUS_BUFFER_OVERFLOW	O buffer de saída não é grande o suficiente para retornar o nome de arquivo completo.
STATUS_BUFFER_TOO_SMALL	O buffer de saída não é grande o suficiente para pelo menos a estrutura base identificada por FileInformationClass.
STATUS_INVALID_INFO_CLASS	Um FileInformationClass inválido foi especificado ou a classe de informações é válida apenas para uma condição especial (por exemplo, válida somente para um diretório especial).
STATUS_INVALID_PARAMETER	Um dos parâmetros é inválido para o sistema de arquivos.

Comentários

NtQueryDirectoryFileEx retorna informações sobre arquivos contidos no diretório representado por FileHandle.

Se fornecido, FileName determina as entradas incluídas na verificação de diretório para todas as chamadas subsequentes para NtQueryDirectoryFileEx para um determinado FileHandle.

Se houver pelo menos uma entrada correspondente, NtQueryDirectoryFileEx criará uma estrutura FILE_XXX_INFORMATION para cada entrada e as armazenará no buffer.

Supondo que pelo menos uma entrada de diretório correspondente seja encontrada, o número de entradas para as quais as informações são retornadas é o menor dos seguintes:

Uma entrada, se SL_RETURN_SINGLE_ENTRY estiver definida em QueryFlags e FileName for NULL.
O número de entradas que correspondem à cadeia de caracteres FileName , se FileName não for NULL. Se a cadeia de caracteres não contiver curingas, poderá haver no máximo uma entrada correspondente.
O número de entradas cujas informações se ajustam ao buffer especificado.
O número de entradas contidas no diretório.

Na primeira chamada para NtQueryDirectoryFileEx, se a estrutura criada para a primeira entrada encontrada for muito grande para caber no buffer de saída, essa rotina fará o seguinte:

Grava a parte fixa da estrutura no buffer de saída de FileInformation. A parte fixa consiste em todos os campos, exceto a cadeia de caracteres FileName final. Na primeira chamada, mas não em chamadas subsequentes, o sistema de E/S garante que o buffer seja grande o suficiente para manter a parte fixa da estrutura FILE_XXX_INFORMATION apropriada.
Grava no buffer de saída o máximo da cadeia de caracteres FileName que caberá.
Retorna um valor de status apropriado, como STATUS_BUFFER_OVERFLOW.

Em cada chamada, NtQueryDirectoryFileEx retorna tantas estruturas FILE_XXX_INFORMATION (uma por entrada de diretório) como podem ser contidas inteiramente no buffer apontado por FileInformation:

Na primeira chamada, NtQueryDirectoryFileEx retornará STATUS_SUCCESS somente se o buffer de saída contiver pelo menos uma estrutura completa.
Em chamadas subsequentes, se o buffer de saída não contiver estruturas, NtQueryDirectoryFileEx retornará STATUS_SUCCESS mas definirá IoStatusBlock-Information> = 0 para notificar o chamador dessa condição. Nesse caso, o chamador deve alocar um buffer maior e chamar NtQueryDirectoryFileEx novamente. Nenhuma informação sobre as entradas restantes é relatada. Assim, exceto nos casos listados acima em que apenas uma entrada é retornada, NtQueryDirectoryFileEx deve ser chamado pelo menos duas vezes para enumerar o conteúdo de um diretório inteiro.

Ao chamar NtQueryDirectoryFileEx, você pode ver alterações feitas no diretório que ocorrem em paralelo com chamadas NtQueryDirectoryFileEx . Esse comportamento depende da implementação do sistema de arquivos subjacente.

A chamada final para NtQueryDirectoryFileEx retorna um buffer de saída vazio e relata um valor de status apropriado, como STATUS_NO_MORE_FILES.

Se NtQueryDirectoryFileEx for chamado várias vezes no mesmo diretório e alguma outra operação alterar o conteúdo desse diretório, qualquer alteração poderá ou não ser vista, dependendo do tempo das operações.

NtQueryDirectoryFileEx retorna zero em qualquer membro de uma estrutura FILE_XXX_INFORMATION que não é compatível com o sistema de arquivos.

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

Para obter informações sobre outras rotinas de consulta de informações de arquivo, consulte Objetos de arquivo.

Observação

Se a chamada para a função NtQueryDirectoryFileEx ocorrer no modo kernel, você deverá usar o nome "ZwQueryDirectoryFileEx" em vez de "NtQueryDirectoryFileEx".

Para chamadas de drivers de modo kernel, as versões NtXxx e ZwXxx de uma rotina do Windows Native System Services 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
Cliente mínimo com suporte	Windows 10, versão 1709
Cabeçalho	ntifs.h
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)