Função FilterAttachAtAltitude (fltuser.h)

  • Artigo

A função FilterAttachAtAltitude é uma função de suporte de depuração que anexa uma nova instância de minifiltro a um volume em uma altitude especificada, substituindo quaisquer configurações no arquivo INF (informações de instalação) do minifiltro.

Sintaxe

HRESULT FilterAttachAtAltitude(
  [in]            LPCWSTR lpFilterName,
  [in]            LPCWSTR lpVolumeName,
  [in]            LPCWSTR lpAltitude,
  [in, optional]  LPCWSTR lpInstanceName,
  [in, optional]  DWORD   dwCreatedInstanceNameLength,
  [out, optional] LPWSTR  lpCreatedInstanceName
);

Parâmetros

[in] lpFilterName

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome do minifiltro para o qual uma instância deve ser criada. Esse parâmetro é necessário e não pode ser NULL.

[in] lpVolumeName

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome do volume ao qual a instância recém-criada deve ser anexada.

A cadeia de caracteres de entrada lpVolumeName pode ser qualquer uma das opções a seguir. A barra invertida à direita (\) é opcional.

  • Uma letra de unidade, como "D:\"
  • Um caminho para um ponto de montagem de volume, como "c:\mnt\edrive\"
  • Um identificador de volume exclusivo (também chamado de nome GUID de volume), como "\?? \Volume{7603f260-142a-11d4-ac67-806d6172696f}\"
  • Um nome de dispositivo não persistente (também chamado de nome de destino ou nome de dispositivo NT), como "\Device\HarddiskVolume1\"
Esse parâmetro é necessário e não pode ser NULL.

[in] lpAltitude

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém um valor numérico especificando a posição de destino que a instância de minifiltro deve ocupar na pilha do volume. Quanto maior o número, maior a posição relativa na pilha. Uma cadeia de caracteres de altitude consiste em um ou mais dígitos no intervalo de 0 a 9 e pode incluir um único ponto decimal. O ponto decimal é opcional. Por exemplo, "100.123456" é uma cadeia de caracteres de altitude válida. Esse parâmetro é necessário e não pode ser NULL.

[in, optional] lpInstanceName

Ponteiro para uma cadeia de caracteres largos terminada em nulo que contém o nome da instância da nova instância. Esse parâmetro é opcional e pode ser NULL. Se esse parâmetro for NULL, a nova instância receberá o nome da instância padrão do minifiltro, conforme descrito na seção Comentários de FltAttachVolume.

[in, optional] dwCreatedInstanceNameLength

Comprimento, em bytes, do buffer para o qual lpCreatedInstanceName aponta. Esse parâmetro é opcional e pode ser zero.

[out, optional] lpCreatedInstanceName

Ponteiro para uma variável alocada pelo chamador que recebe o nome da instância da nova instância se a instância for anexada com êxito ao volume. Esse parâmetro é opcional e pode ser NULL. Se não for NULL, o buffer deverá ser grande o suficiente para manter INSTANCE_NAME_MAX_CHARS caracteres mais um terminador NULL.

Valor retornado

FilterAttachAtAltitude retorna S_OK se tiver êxito. Caso contrário, ele retornará um valor de erro, como um dos seguintes.

Código de retorno Descrição
ERROR_FLT_INSTANCE_ALTITUDE_COLLISION
 Uma instância já existe nessa altitude no volume especificado.
ERROR_FLT_INSTANCE_NAME_COLLISION
 Uma instância já existe com esse nome no volume especificado.

Comentários

Um aplicativo só deve usar FilterAttachAtAltitude para depuração. Ele não deve chamar essa função em uma versão de varejo do aplicativo.

FilterAttachAtAltitude é o equivalente a Win32 de FltAttachVolumeAtAltitude.

O termo "altitude" refere-se à posição que uma instância ocupa (ou deve ocupar) na pilha de instâncias 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.

A altitude é especificada por uma cadeia de caracteres de altitude, que é uma matriz de caracteres largos que contém um ou mais dígitos decimais no intervalo de 0 a 9, e pode incluir um único ponto decimal. O ponto decimal é opcional. 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 retornado em lpCreatedInstanceName é exclusivo em todo o sistema.

Para desanexar uma instância de minifiltro de um volume, chame FilterDetach.

Requisitos

   
Plataforma de Destino Universal
Cabeçalho fltuser.h (inclua Fltuser.h)
Biblioteca FltLib.lib
DLL FltLib.dll

Confira também

FilterAttach

FilterDetach

FltAttachVolumeAtAltitude