Função FltGetLowerInstance (fltkernel.h)

Artigo
08/07/2023

A rotina FltGetLowerInstance retorna um ponteiro de instância opaco para a próxima instância de driver de minifiltro inferior, se houver uma, que é anexada abaixo de uma determinada instância de driver de minifiltro no mesmo volume.

Sintaxe

NTSTATUS FLTAPI FltGetLowerInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *LowerInstance
);

Parâmetros

[in] CurrentInstance

Ponteiro de instância opaca para a instância do driver de minifiltro para a qual a instância do driver de minifiltro inferior é solicitada.

[out] LowerInstance

Ponteiro para uma variável alocada pelo chamador que recebe um ponteiro de instância de driver de minifiltro opaco para a próxima instância do driver de minifiltro inferior. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

FltGetLowerInstance retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como o seguinte:

Código de retorno	Descrição
STATUS_NO_MORE_ENTRIES	Nenhuma instância de driver de minifiltro inferior foi encontrada. Esse é um código de aviso.

Comentários

Diz-se que uma instância está abaixo de outra se estiver anexada a uma altitude mais baixa no mesmo volume. O termo "altitude" refere-se à posição que uma instância ocupa (ou deve ocupar) na pilha de instâncias do driver de minifiltro para um volume. Quanto maior a altitude, mais distante a instância fica do sistema de arquivos base na pilha. Somente uma instância pode ser anexada a uma determinada altitude em um determinado volume.

Altitude é especificada por uma cadeia de caracteres de altitude, que é uma cadeia de caracteres Unicode contada que consiste em um ou mais dígitos decimais de 0 a 9, e pode incluir um único ponto decimal. Por exemplo, "100.123456" e "03333" são cadeias de caracteres de altitude válidas.

A cadeia de caracteres "03333" representa uma altitude maior que "100,123456". (Zeros à esquerda e à direita são ignorados.) Em outras palavras, uma instância cuja altitude é "03333" está mais distante do sistema de arquivos base do que uma instância cuja altitude é "100,123456". No entanto, essa comparação só será significativa se ambas as instâncias estiverem anexadas ao mesmo volume.

FltGetLowerInstance adiciona uma referência de rundown ao ponteiro de instância opaco retornado no parâmetro LowerInstance . Quando esse ponteiro não for mais necessário, o chamador deverá liberá-lo chamando FltObjectDereference. Portanto, cada chamada bem-sucedida para FltGetLowerInstance deve ser correspondida por uma chamada subsequente para FltObjectDereference.