Função ZwQueryDirectoryFile (ntifs.h)

Artigo
12/21/2024

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

Sintaxe

NTSYSAPI NTSTATUS ZwQueryDirectoryFile(
  [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,
  [in]           FILE_INFORMATION_CLASS FileInformationClass,
  [in]           BOOLEAN                ReturnSingleEntry,
  [in, optional] PUNICODE_STRING        FileName,
  [in]           BOOLEAN                RestartScan
);

Parâmetros

[in] FileHandle

Um identificador retornado por ZwCreateFile ou ZwOpenFile 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 de NULL nãopara de Eventos 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 o FileHandle ser definido como o estado Sinalizado.

[in, optional] ApcRoutine

Um endereço de uma rotina de APC opcional fornecida pelo chamador a ser chamado 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 é concluída, esse contexto é passado para o APC, se um foi 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. Deve ser NULL se de ApcRoutine estiver 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 de 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 oFileInformationClass determinado.

[in] FileInformationClass

O tipo de informação a ser retornado sobre arquivos no diretório. Consulte o parâmetro FileInformationClass de NtQueryDirectoryFileEx para obter a lista de valores possíveis.

[in] ReturnSingleEntry

Defina como TRUE se apenas uma única entrada deve ser retornada, FALSE caso contrário. Se esse parâmetro for TRUE, ZwQueryDirectoryFile retornará apenas a primeira entrada encontrada.

[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 estiver 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, todos os arquivos serão incluídos se ReturnSingleEntry for FALSE; um arquivo será incluído se ReturnSingleEntry estiver VERDADEIRO.

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

[in] RestartScan

Defina como VERDADEIRO se a verificação for iniciada na primeira entrada no diretório. Defina como FALSE se retomar a verificação de uma chamada anterior.

Quando a rotina de ZwQueryDirectoryFile é chamada para um identificador específico, o parâmetro RestartScan é tratado como se estivesse definido como TRUE, independentemente de seu valor. Nas chamadas ZwQueryDirectoryFile subsequentes, o valor do parâmetro RestartScan é respeitado.

Valor de retorno

A rotina ZwQueryDirectoryFile retorna STATUS_SUCCESS ou um status de erro apropriado. O conjunto de valores de status de erro que podem ser retornados é específico do sistema de arquivos. ZwQueryDirectoryFile também retorna o número de bytes realmente gravados no buffer de FileInformation fornecido no membro de Informações do IoStatusBlock. Consulte NtQueryDirectoryFileEx para obter uma lista de alguns códigos de erro possíveis.

Observações

A rotina ZwQueryDirectoryFile 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 ZwQueryDirectoryFile para um determinado FileHandle.

Se houver pelo menos uma entrada correspondente, ZwQueryDirectoryFile criará uma estrutura de_INFORMATION XXX FILE_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 do seguinte:

Uma entrada, se ReturnSingleEntry for true e FileName estiver NULL.
O número de entradas que correspondem à cadeia de caracteres FileName , se FileName não estiver NULL. Se a cadeia de caracteres não contiver caracteres curinga, 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 ZwQueryDirectoryFile, 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 para buffer de saída doFileInformation. 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 de_INFORMATION XXX FILE_apropriada.
Grava no buffer de saída a maior parte da cadeia de caracteres FileName que caberá.
Retorna um valor de status apropriado, como STATUS_BUFFER_OVERFLOW.

Em cada chamada, ZwQueryDirectoryFile retorna quantas estruturas de_INFORMATION XXX FILE_(uma por entrada de diretório) podem ser contidas inteiramente no buffer apontado por FileInformation:

Na primeira chamada, ZwQueryDirectoryFile retornará STATUS_SUCCESS somente se o buffer de saída contiver pelo menos uma estrutura completa.
Nas chamadas subsequentes, se o buffer de saída não contiver estruturas, ZwQueryDirectoryFile 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 ZwQueryDirectoryFile novamente. Nenhuma informação sobre as entradas restantes é relatada. Assim, exceto nos casos listados acima em que apenas uma entrada é retornada, ZwQueryDirectoryFile deve ser chamado pelo menos duas vezes para enumerar o conteúdo de um diretório inteiro.

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

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

Se ZwQueryDirectoryFile 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.

ZwQueryDirectoryFile retorna zero em qualquer membro de uma estrutura de_INFORMATION XXX FILE_que não é compatível com o sistema de arquivos.

Os chamadores de ZwQueryDirectoryFile 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.

Nota

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

Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de 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 de serviços do sistema nativo.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP.
da Plataforma de Destino	Universal
cabeçalho	ntifs.h (inclua Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)