Função NtQueryDirectoryFile (ntifs.h)
A rotina NtQueryDirectoryFile retorna vários tipos de informações sobre arquivos no diretório especificado por um determinado identificador de arquivo.
Sintaxe
__kernel_entry NTSYSCALLAPI NTSTATUS NtQueryDirectoryFile(
[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 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 deverá 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 deverá ser NULL se o chamador aguardar que o FileHandle seja definido como o estado Sinalizado.
[in, optional] ApcRoutine
Um endereço de uma rotina 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 será 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 a 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 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.
[in] FileInformationClass
O tipo de informação a ser retornado sobre arquivos no diretório. Tipo de informação a ser retornada 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; caso contrário, FALSE . Se esse parâmetro for TRUE, NtQueryDirectoryFile 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) dentro do diretório especificado por FileHandle. Esse parâmetro é opcional e pode ser NULL.
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, todos os arquivos serão incluídos.
O FileName é usado como uma expressão de pesquisa e é capturado na primeira chamada para NtQueryDirectoryFile para um determinado identificador. As chamadas subsequentes para NtQueryDirectoryFile usarão a expressão de pesquisa definida na primeira chamada. O parâmetro FileName passado para chamadas subsequentes será ignorado.
[in] RestartScan
Defina como TRUE 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 NtQueryDirectoryFile é chamada para um identificador específico, o parâmetro RestartScan é tratado como se tivesse sido definido como TRUE, independentemente de seu valor. Nas chamadas subsequentes de NtQueryDirectoryFile , o valor do parâmetro RestartScan é respeitado.
Retornar valor
A rotina NtQueryDirectoryFileretorna STATUS_SUCCESS ou um erro apropriado status. O conjunto de erros status valores que podem ser retornados é específico do sistema de arquivos. NtQueryDirectoryFiletambém retorna o número de bytes realmente gravados no buffer FileInformation fornecido no membro Information de IoStatusblock. Consulte NtQueryDirectoryFileEx para obter uma lista de alguns códigos de erro possíveis.
Comentários
A rotina NtQueryDirectoryFile retorna informações sobre arquivos contidos no diretório representado por FileHandle.
Se fornecido, o valor do parâmetro FileName determina as entradas incluídas na verificação de diretório para todas as chamadas subsequentes para NtQueryDirectoryFile para um determinado FileHandle.
Se houver pelo menos uma entrada correspondente, NtQueryDirectoryFile 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 ReturnSingleEntry for TRUE e FileName for NULL.
- O número de entradas que correspondem à cadeia de caracteres FileName , se FileName não for NULL. (Observe que, 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 NtQueryDirectoryFile, se a estrutura criada para a primeira entrada encontrada for muito grande para caber no buffer de saída, a rotina gravará a parte fixa da estrutura no buffer de saída. Em seguida, a rotina grava no buffer de saída o máximo da cadeia de caracteres FileName que caberá. (A parte fixa da estrutura 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.) Quando isso acontece, NtQueryDirectoryFile retorna um valor de status apropriado, como STATUS_BUFFER_OVERFLOW.
Em cada chamada, NtQueryDirectoryFile 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, NtQueryDirectoryFile 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, NtQueryDirectoryFile 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 NtQueryDirectoryFile novamente. Nenhuma informação sobre as entradas restantes é relatada. Portanto, exceto nos casos listados acima em que apenas uma entrada é retornada, NtQueryDirectoryFile deve ser chamado pelo menos duas vezes para enumerar o conteúdo de um diretório inteiro.
Ao chamar NtQueryDirectoryFile, você pode ver alterações feitas no diretório que ocorrem em paralelo com chamadas de NtQueryDirectoryFile . Esse comportamento depende da implementação do sistema de arquivos subjacente.
A chamada final para NtQueryDirectoryFile retorna um buffer de saída vazio e relata um valor de status apropriado, como STATUS_NO_MORE_FILES.
Se NtQueryDirectoryFile 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.
NtQueryDirectoryFileretorna zero em qualquer membro de uma estrutura FILE_XXX_INFORMATION que não é compatível com o sistema de arquivos.
Os chamadores de NtQueryDirectoryFile 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 NtQueryDirectoryFile ocorrer no modo de usuário, você deverá usar o nome "NtQueryDirectoryFile" em vez de "ZwQueryDirectoryFile".
Para chamadas de drivers de modo kernel, as versões XXX Nt XXX 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 XXX 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 XP |
| Plataforma de Destino | Universal |
| Cabeçalho | ntifs.h (inclua Ntifs.h) |
| Biblioteca | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (consulte a seção Comentários) |
| Regras de conformidade da DDI | HwStorPortProhibitedDDIs, PowerIrpDDis |