Função FltQueryDirectoryFileEx (fltkernel.h)

Artigo
08/07/2023

FltQueryDirectoryFileEx retorna vários tipos de informações sobre arquivos no diretório especificado por um determinado objeto de arquivo.

Sintaxe

NTSTATUS FLTAPI FltQueryDirectoryFileEx(
  PFLT_INSTANCE          Instance,
  PFILE_OBJECT           FileObject,
  PVOID                  FileInformation,
  ULONG                  Length,
  FILE_INFORMATION_CLASS FileInformationClass,
  ULONG                  QueryFlags,
  PUNICODE_STRING        FileName,
  PULONG                 LengthReturned
);

Parâmetros

Instance

Ponteiro opaco para a instância do driver de minifiltro que está iniciando essa E/S.

FileObject

Ponteiro para o objeto de arquivo que representa o diretório que está sendo consultado.

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 .

Length

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

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.

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)	Se esse sinalizador estiver definido, a verificação será iniciada na primeira entrada no 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 for 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)	Se esse sinalizador estiver definido, a verificação deverá começar em uma posição indexada especificada no diretório . Esse sinalizador só poderá ser definido se você gerar seu próprio IRP IRP_MJ_DIRECTORY_CONTROL; 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)	Se esse sinalizador estiver definido, todos os filtros do sistema de arquivos que executam virtualização de diretório ou expansão just-in-time deverão 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 é encadeado único para evitar a corrupção do estado do cursor. Esse sinalizador instrui o sistema de arquivos a não atualizar as 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 será retomada 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.

FileName

Ponteiro para uma estrutura de UNICODE_STRING alocada pelo chamador com a cadeia de caracteres Unicode que contém o nome de um arquivo (ou vários arquivos, se caracteres curinga forem usados) dentro do diretório especificado por FileObject. Esse parâmetro é opcional e pode ser NULL. Se fileName for NULL, todos os arquivos serão incluídos.

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 o sinalizador QueryFlagsResetScan estiver definido, o valor de FileName será ignorado.

LengthReturned

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

Retornar valor

FltQueryDirectoryFileEx retorna STATUS_SUCCESS ou um código de erro apropriado. O conjunto de erros status valores que podem ser retornados é específico do sistema de arquivos.

Comentários

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

A primeira chamada para FltQueryDirectoryFileEx 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 QueryFlags e FileName. Se houver pelo menos uma entrada correspondente, FltQueryDirectoryFileEx criará uma estrutura FILE_XXX_INFORMATION (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 é o menor dos seguintes:

Uma entrada, se o sinalizador SL_RETURN_SINGLE_ENTRY estiver definido em QueryFlags 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 apontado por FileInformation.
O número de entradas contidas no diretório.

Na primeira chamada para FltQueryDirectoryFileEx, se a estrutura criada para a primeira entrada encontrada 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. O subsistema de E/S garante que o buffer seja grande o suficiente para manter a parte fixa da estrutura FILE_XXX_INFORMATION apropriada (somente na primeira chamada e não em chamadas subsequentes). Quando isso acontece, FltQueryDirectoryFileEx retorna um valor status de STATUS_BUFFER_OVERFLOW. Também na primeira chamada para FltQueryDirectoryFileEx, se não houver nenhum arquivo no diretório FileObject que corresponda ao parâmetro FileName , FltQueryDirectoryFileEx retornará STATUS_NO_SUCH_FILE.

Em cada chamada, FltQueryDirectoryFileEx retorna tantas estruturas FILE_XXX_INFORMATION (uma por entrada de diretório) como 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, FltQueryDirectoryFileEx 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 FltQueryDirectoryFileEx retorna um buffer de saída vazio e relata um valor de status não-erro de STATUS_NO_MORE_FILES.

Nota: Quando FltQueryDirectoryFileEx é 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 FltQueryDirectoryFileEx. Em chamadas subsequentes, FltQueryDirectoryFileEx retoma a verificação de diretório onde quer que ela parou nessa mesma enumeração. No entanto, entre chamadas para FltQueryDirectoryFileEx, as entradas de diretório reais podem ser alteradas para que não estejam mais sincronizadas com a enumeração original.

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

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