Função FltQueryDirectoryFileEx (fltkernel.h)

Artigo
07/16/2024

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 oFileInformationClass determinado.

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 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)	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_MJ_DIRECTORY_CONTROLIRP; o índice é especificado no IRP. 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 a virtualização do diretório ou a 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 porinformações de cursor de diretório FileObject. Quando vários threads fazem consultas usando o mesmo FileObject, o acesso à estrutura FileObject poré encadeado único para evitar a corrupção do estado do cursor. Esse sinalizador informa ao sistema de arquivos para não atualizar poro FileObject informações de estado do cursor, 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 curinga 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 curingas 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 estiver 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 for definido, o valor de FileName será ignorado.

LengthReturned

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

Valor de retorno

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

Observações

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 de QueryFlags e FileName. Se houver pelo menos uma entrada correspondente, FltQueryDirectoryFileEx 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 o sinalizador de SL_RETURN_SINGLE_ENTRY estiver definido em de QueryFlags e FileName for 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 encaixam no 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 de_INFORMATION XXX FILE_apropriada (somente na primeira chamada e não nas chamadas subsequentes). Quando isso acontece, FltQueryDirectoryFileEx retorna um valor de 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 de_INFORMATION XXX FILE_(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 de não erro de STATUS_NO_MORE_FILES.

Observação: 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. Nas chamadas subsequentes, FltQueryDirectoryFileEx retoma a verificação de diretório onde quer que tenha deixado de fora nessa mesma enumeração. No entanto, entre as chamadas para FltQueryDirectoryFileEx, as entradas reais do diretório podem ser alteradas para que não estejam mais sincronizadas com a enumeração original.

FltQueryDirectoryFileEx retorna zero em qualquer membro de uma estrutura de_INFORMATION XXX FILE_que não tem suporte do 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.