Função FltAttachVolumeAtAltitude (fltkernel.h)

Artigo
03/01/2024

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 quaisquer 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 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 do nome do driver de minifiltro e a cadeia de caracteres de altitude para a qual Altitude aponta. O nome gerado é truncado, se necessário, para INSTANCE_NAME_MAX_CHARS caracteres.

[out, optional] RetInstance

Ponteiro para uma variável alocada pelo chamador que recebe um ponteiro de instância opaco para a instância recém-criada. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

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

Código de retorno	Descrição
STATUS_FLT_DELETING_OBJECT	O Filtro ou Volume especificado está sendo dividido. Este é um código de erro.
STATUS_FLT_FILTER_NOT_READY	O driver de minifiltro não iniciou a filtragem. Para obter mais informações, consulte FltStartFiltering. Este é um código de erro.
STATUS_FLT_INSTANCE_ALTITUDE_COLLISION	Uma instância já existe nessa altitude no volume especificado. Este é um código de erro.
STATUS_FLT_INSTANCE_NAME_COLLISION	Já existe uma instância com esse nome no volume especificado. Este é um código de erro.
STATUS_INSUFFICIENT_RESOURCES	FltAttachVolumeAtAltitude encontrou uma falha de alocação de pool. Este é um código de erro.
STATUS_INVALID_PARAMETER	A estrutura de UNICODE_STRING para a qual Altitude aponta não continha uma cadeia de caracteres de altitude válida. Este é um código de erro.

Comentários

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 de 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.

Altitude é especificada por uma cadeia de caracteres de altitude, que é uma matriz de caracteres largos que contém 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 enquanto a instância estiver 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.