Função FltAttachVolumeAtAltitude (fltkernel.h)
FltAttachVolumeAtAltitude é uma rotina de suporte de depuração que anexa uma instância de driver de minifiltro a um volume em uma altitude especificada, substituindo todas as configurações no arquivo INF do driver de minifiltro.
Sintaxe
NTSTATUS FLTAPI FltAttachVolumeAtAltitude(
[in, out] PFLT_FILTER Filter,
[in, out] PFLT_VOLUME Volume,
[in] PCUNICODE_STRING Altitude,
[in, optional] PCUNICODE_STRING InstanceName,
[out, optional] PFLT_INSTANCE *RetInstance
);
Parâmetros
[in, out] Filter
Ponteiro de filtro opaco para o chamador. Esse parâmetro é necessário e não pode ser NULL.
[in, out] Volume
Ponteiro de volume opaco para o volume ao qual a instância do driver de minifiltro deve ser anexada. Esse parâmetro é necessário e não pode ser NULL.
[in] Altitude
Ponteiro para uma estrutura UNICODE_STRING que contém a cadeia de caracteres de altitude para a instância. Esse parâmetro é necessário e não pode ser NULL. (Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.)
[in, optional] InstanceName
Ponteiro para uma estrutura de UNICODE_STRING que contém o nome da instância da nova instância. Esse parâmetro é opcional e pode ser NULL. Se for NULL, FltAttachVolumeAtAltitude gerará um nome de instância a partir do nome do driver do minifiltro e da cadeia de caracteres de altitude que Altitude aponta. O nome gerado é truncado, se necessário, para INSTANCE_NAME_MAX_CHARS caracteres.
[out, optional] RetInstance
Ponteiro para uma variável alocada por chamador que recebe um ponteiro de instância opaca para a instância recém-criada. Esse parâmetro é opcional e pode ser NULL.
Valor de retorno
FltAttachVolumeAtAltitude retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:
Observações
Um driver de minifiltro só deve usar FltAttachVolumeAtAltitude para depuração. Ele não deve chamar essa rotina em uma versão de varejo do driver de minifiltro.
FltAttachVolumeAtAltitude é o equivalente ao kernel da função FilterAttachAtAltitude do Win32.
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 matriz de caracteres largos contendo um ou mais dígitos decimais de 0 a 9; a matriz 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.
O nome da instância especificado no parâmetro InstanceName é necessário para ser exclusivo em todo o sistema.
fltAttachVolumeAtAltitude retorna um ponteiro de instância opaco para a nova instância em *RetInstance. Esse valor de ponteiro identifica exclusivamente a instância do driver de minifiltro e permanece constante desde que a instância esteja anexada ao volume.
FltAttachVolumeAtAltitude adiciona uma referência de rundown ao ponteiro de instância opaco retornado em *RetInstance. Quando esse ponteiro não for mais necessário, o chamador deverá liberá-lo chamando FltObjectDereference. Portanto, cada chamada bem-sucedida para FltAttachVolumeAtAltitude deve ser correspondida por uma chamada subsequente para FltObjectDereference.
Para comparar as altitudes de duas instâncias de driver de minifiltro anexadas ao mesmo volume, chame FltCompareInstanceAltitudes.
Para desanexar uma instância de driver de minifiltro de um volume, chame FltDetachVolume.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino | Universal |
| cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| biblioteca | FltMgr.lib |
| IRQL | PASSIVE_LEVEL |