Função FltGetVolumeInstanceFromName (fltkernel.h)

Artigo
08/07/2023

A rotina FltGetVolumeInstanceFromName retorna um ponteiro de instância opaco para a instância de driver de minifiltro fornecida no volume fornecido.

Sintaxe

NTSTATUS FLTAPI FltGetVolumeInstanceFromName(
  [in, optional] PFLT_FILTER      Filter,
  [in]           PFLT_VOLUME      Volume,
  [in, optional] PCUNICODE_STRING InstanceName,
  [out]          PFLT_INSTANCE    *RetInstance
);

Parâmetros

[in, optional] Filter

Ponteiro de filtro opaco para o driver de minifiltro que possui a instância. Esse parâmetro é opcional e pode ser NULL.

[in] Volume

Ponteiro opaco para o volume ao qual a instância está anexada. Deve ser um identificador de volume válido. Esse parâmetro é necessário e não pode ser NULL. (Definir esse parâmetro como um valor inválido faz com que o sistema asserte em um build verificado.)

[in, optional] InstanceName

Ponteiro para uma estrutura de UNICODE_STRING alocada pelo chamador que contém o nome da instância no volume. (Este é o valor InstanceName que foi passado para FltAttachVolume ou FltAttachVolumeAtAltitude quando a instância foi criada.) Esse parâmetro é opcional e pode ser NULL. Se for NULL, FltGetVolumeInstanceFromName retornará a instância correspondente mais alta encontrada.

[out] RetInstance

Ponteiro para uma variável alocada pelo chamador que recebe um ponteiro de instância opaco para a instância que corresponde aos valores de Filter, Volume e InstanceName. Esse parâmetro é necessário e não pode ser NULL.

Retornar valor

FltGetVolumeInstanceFromName retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_DELETING_OBJECT	A instância está sendo interrompida. Este é um código de erro.
STATUS_FLT_INSTANCE_NOT_FOUND	Nenhuma instância correspondente foi encontrada. Este é um código de erro.

Comentários

FltGetVolumeInstanceFromName pesquisa a lista de instâncias de driver de minifiltro anexadas ao volume especificado no parâmetro Volume na ordem de diminuição da altitude, começando com a instância superior. Se mais de uma instância corresponder aos valores fornecidos para os parâmetros Filter, Volume e InstanceName , FltGetVolumeInstanceFromName retornará a instância correspondente mais alta encontrada.

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.

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