Função FltQueryDirectoryFile (fltkernel.h)

Artigo
12/22/2024

A rotina FltQueryDirectoryFile retorna vários tipos de informações sobre arquivos no diretório especificado por um determinado objeto de arquivo. Use FltQueryDirectoryFileEx para obter um controle de consulta maior.

Sintaxe

NTSTATUS FLTAPI FltQueryDirectoryFile(
  [in]            PFLT_INSTANCE          Instance,
  [in]            PFILE_OBJECT           FileObject,
  [out]           PVOID                  FileInformation,
  [in]            ULONG                  Length,
  [in]            FILE_INFORMATION_CLASS FileInformationClass,
  [in]            BOOLEAN                ReturnSingleEntry,
  [in, optional]  PUNICODE_STRING        FileName,
  [in]            BOOLEAN                RestartScan,
  [out, optional] PULONG                 LengthReturned
);

Parâmetros

[in] Instance

Ponteiro opaco para a instância do driver de filtro que inicia a E/S.

[in] FileObject

Ponteiro para o objeto de arquivo que representa o diretório a ser verificado.

[out] FileInformation

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

Tamanho, em bytes, do buffer apontado por FileInformation. O chamador deve definir esse parâmetro de acordo com oFileInformationClass determinado.

[in] FileInformationClass

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, FALSE caso contrário. Se esse parâmetro for TRUE, FltQueryDirectoryFile retornará apenas a primeira entrada encontrada.

[in, optional] FileName

Ponteiro 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 FileObject. Esse parâmetro é opcional e pode ser NULL.

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 RestartScan for FALSE, o valor de FileName 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. O chamador deve definir esse parâmetro para TRUE ao chamar FltQueryDirectoryFile pela primeira vez.

[out, optional] LengthReturned

Recebe o número de bytes realmente gravados no buffer FileInformation fornecido.

Valor de retorno

FltQueryDirectoryFile retorna STATUS_SUCCESS ou um status de erro apropriado. Observe que o conjunto de valores de status de erro que podem ser retornados é específico do sistema de arquivos.

Observações

FltQueryDirectoryFile retorna informações sobre arquivos contidos no diretório representado por FileObject.

A primeira chamada para FltQueryDirectoryFile determina o conjunto de entradas a serem incluídas na verificação de diretório para todas as chamadas subsequentes, com base nos valores de ReturnSingleEntry, FileNamee RestartScan. Se houver pelo menos uma entrada correspondente, FltQueryDirectoryFile criará uma estrutura de_INFORMATION XXX FILE_(consulte a tabela acima) para cada entrada por sua vez e armazenará a estrutura 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 é a menor das seguintes:

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. (Observe que, 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 FltQueryDirectoryFile, se a estrutura criada para a primeira entrada for muito grande para caber no buffer de saída, somente a parte fixa da estrutura será retornada. A parte fixa consiste em todos os campos da estrutura, exceto a cadeia de caracteres FileName final. Na primeira chamada, mas não nas seguintes, 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. Quando isso acontece, FltQueryDirectoryFile retorna um valor de status apropriado, como STATUS_BUFFER_OVERFLOW. Também na primeira chamada para FltQueryDirectoryFile, se não houver nenhum arquivo no diretório FileObject que corresponda ao parâmetro FileName, FltQueryDirectoryFile retornará um valor de status apropriado, como STATUS_NO_SUCH_FILE.

Em cada chamada, FltQueryDirectoryFile retorna quantas estruturas de_INFORMATION XXX FILE_(uma por entrada de diretório) podem ser contidas inteiramente no buffer apontado por FileInformation. Desde que o buffer de saída contenha pelo menos uma estrutura completa, o valor de status retornado é STATUS_SUCCESS. Nenhuma informação sobre as entradas restantes é relatada. Assim, exceto nos casos listados acima em que apenas uma entrada é retornada, FltQueryDirectoryFile deve ser chamado pelo menos duas vezes para enumerar o conteúdo de um diretório inteiro (por exemplo, quando o parâmetro FileName contém um ou mais caracteres curinga ou é NULL).

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

Nota

Quando FltQueryDirectoryFile é chamado várias vezes no mesmo diretório, é possível que o número de entradas para as quais as informações são retornadas seja menor do que o esperado. Isso ocorre porque o conjunto de entradas a serem incluídas na verificação de diretório é corrigido na primeira chamada para FltQueryDirectoryFile. Nas chamadas subsequentes, FltQueryDirectoryFile retoma a verificação de diretório onde quer que tenha deixado de fora nessa mesma enumeração. No entanto, entre as chamadas para FltQueryDirectoryFile, as entradas de diretório reais podem ser alteradas para que não estejam mais sincronizadas com a enumeração original.

FltQueryDirectoryFile retorna zero em qualquer membro de uma estrutura de_INFORMATION XXX FILE_que não tem suporte no sistema de arquivos.

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

Os chamadores de FltQueryDirectoryFile devem estar em execução em IRQL = PASSIVE_LEVEL e com APCs habilitadas. Para obter mais informações, consulte Desabilitando APCs.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista
da Plataforma de Destino	Universal
cabeçalho	fltkernel.h (inclua Fltkernel.h)
biblioteca	FltMgr.lib
de DLL	Fltmgr.sys
IRQL	PASSIVE_LEVEL (consulte a seção Comentários)