Função FltGetVolumeInstanceFromName (fltkernel.h)
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 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 por chamador que recebe um ponteiro de instância opaco para a instância que corresponde aos valores de Filter, Volumee InstanceName. Esse parâmetro é necessário e não pode ser NULL.
Valor de retorno
FltGetVolumeInstanceFromName retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:
| Código de retorno | Descrição |
|---|---|
|
A instância está sendo demolida. Este é um código de erro. |
|
Nenhuma instância correspondente foi encontrada. Este é um código de erro. |
Observações
FltGetVolumeInstanceFromName pesquisa a lista de instâncias de driver de minifiltro anexadas ao volume especificado no parâmetro Volume em ordem de diminuição da altitude, começando com a instância mais alta. Se mais de uma instância corresponder aos valores fornecidos para os parâmetros Filter, Volumee InstanceName parâmetros, 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 é do sistema de arquivos base na pilha. Somente uma instância pode ser anexada a uma determinada altitude em um determinado volume.
A 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.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| biblioteca | FltMgr.lib |
| de DLL | Fltmgr.sys |
| IRQL | <= APC_LEVEL |