Função FltGetTopInstance (fltkernel.h)

Artigo
02/26/2024

A rotina FltGetTopInstance retorna um ponteiro de instância opaco para a instância de driver de minifiltro anexada na parte superior da pilha de instâncias para um determinado volume.

Sintaxe

NTSTATUS FLTAPI FltGetTopInstance(
  [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 opaco para a instância inferior desse volume. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

FltGetTopInstance 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. Este é um código de aviso.

Comentários

Diz-se que uma instância está na parte superior da pilha de instâncias do driver de minifiltro se sua altitude for maior 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 é 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.

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