Função FltGetBottomInstance (fltkernel.h)

Artigo
03/14/2023

FltGetBottomInstance retorna um ponteiro de instância opaco para a instância do driver de minifiltro, se houver um, que é anexado na parte inferior da pilha de instâncias para um determinado volume.

Sintaxe

NTSTATUS FLTAPI FltGetBottomInstance(
  [in]  PFLT_VOLUME   Volume,
  [out] PFLT_INSTANCE *Instance
);

Parâmetros

[in] Volume

Ponteiro opaco para o volume.

[out] Instance

Ponteiro para uma variável alocada pelo chamador que recebe um ponteiro de instância opaca para a instância inferior desse volume. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

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

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

Comentários

Diz-se que uma instância está na parte inferior da pilha de instâncias do driver de minifiltro se sua altitude for menor do que a de todas as outras instâncias anexadas ao mesmo volume. O termo "altitude" refere-se à posição que uma instância ocupa 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.

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