Função FltGetUpperInstance (fltkernel.h)

Artigo
08/07/2023

A rotina FltGetUpperInstance retorna um ponteiro de instância opaco para a próxima instância de driver de minifiltro superior, se houver uma, anexada acima de uma determinada instância de driver de minifiltro no mesmo volume.

Sintaxe

NTSTATUS FLTAPI FltGetUpperInstance(
  [in]  PFLT_INSTANCE CurrentInstance,
  [out] PFLT_INSTANCE *UpperInstance
);

Parâmetros

[in] CurrentInstance

Ponteiro de instância opaco para a instância para a qual a próxima instância superior é solicitada.

[out] UpperInstance

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

Retornar valor

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

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

Comentários

Diz-se que uma instância está acima de outra se estiver anexada a uma altitude mais alta 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 é 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 no intervalo 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.

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