PFLT_INSTANCE_SETUP_CALLBACK função de retorno de chamada (fltkernel.h)

Artigo
02/06/2025

Um driver de minifiltro pode registrar uma rotina de tipo PFLT_INSTANCE_SETUP_CALLBACK como rotina de instanceSetupCallback do driver de minifiltro.

Sintaxe

PFLT_INSTANCE_SETUP_CALLBACK PfltInstanceSetupCallback;

NTSTATUS PfltInstanceSetupCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_SETUP_FLAGS Flags,
  [in] DEVICE_TYPE VolumeDeviceType,
  [in] FLT_FILESYSTEM_TYPE VolumeFilesystemType
)
{...}

Parâmetros

[in] FltObjects

Ponteiro para uma estrutura FLT_RELATED_OBJECTS que contém ponteiros opacos para os objetos relacionados à operação atual.

[in] Flags

Máscara de bits de sinalizadores que indicam por que a instância está sendo anexada. Pode ser um ou mais dos seguintes:

Bandeira	Significado
FLTFL_INSTANCE_SETUP_AUTOMATIC_ATTACHMENT (0x00000001)	A instância está sendo anexada automaticamente. O driver de minifiltro acabou de ser carregado e está sendo anexado a todos os volumes existentes ou está sendo anexado a um volume recém-montado.
FLTFL_INSTANCE_SETUP_MANUAL_ATTACHMENT (0x00000002)	A instância está sendo anexada manualmente porque um aplicativo de modo de usuário chamou FilterAttach ou FilterAttachAtAltitude, ou porque um componente do modo kernel chamou FltAttachVolume ou FltAttachVolumeAtAltitude
FLTFL_INSTANCE_SETUP_NEWLY_MOUNTED_VOLUME (0x00000004)	A instância está sendo anexada automaticamente a um volume recém-montado.
FLTFL_INSTANCE_SETUP_DETACHED_VOLUME (0x00000008)	A instância está sendo anexada a um volume desanexado. É possível, em alguns sistemas de arquivos (como FAT e CDFS, que são usados por algumas unidades de mídia removíveis), reanexar um volume depois que ele tiver desanexado. Um volume será desanexado se não tiver nenhuma pilha de armazenamento associada. Um volume nesse estado geralmente é um volume desmontado que ainda tem arquivos abertos.
FLTFL_INSTANCE_SETUP_DEV_VOLUME (0x00000010)	A instância está sendo anexada a um volume formatado como um volume de desenvolvedor. Os filtros do sistema de arquivos podem habilitar otimizações que não exigem que um administrador confie no volume em um determinado computador. Disponível a partir do Windows 11, versão 22H2 atualização de setembro.
FLTFL_INSTANCE_SETUP_TRUSTED_VOLUME (0x00000020)	Indica que um administrador em um determinado computador confiou nesse volume e está disposto a habilitar otimizações como não ter filtros antivírus anexados ao volume. Essas informações são mantidas no registro em um determinado computador. Isso pode ser usado pelos filtros do sistema de arquivos para habilitar otimizações que exigem que um administrador confie no volume em um determinado computador. Disponível a partir do Windows 11, versão 22H2 atualização de setembro.

[in] VolumeDeviceType

tipo de dispositivo do volume do sistema de arquivos. Deve ser um dos seguintes:

FILE_DEVICE_CD_ROM_FILE_SYSTEM (0x00000003)
FILE_DEVICE_DISK_FILE_SYSTEM (0x00000008)
FILE_DEVICE_NETWORK_FILE_SYSTEM (0x00000014)

[in] VolumeFilesystemType

Tipo de sistema de arquivos do volume. Os valores possíveis são listados em FLT_FILESYSTEM_TYPE.

Valor de retorno

Essa rotina de retorno de chamada retorna STATUS_SUCCESS ou um valor NTSTATUS, como o seguinte:

Código de retorno	Descrição
STATUS_FLT_DO_NOT_ATTACH	Retornar esse valor impede que a instância do driver de minifiltro seja anexada ao volume fornecido. Este é um código de erro.

Observações

Nota

Não execute nenhuma sincronização de thread ou comunicação entre processos em sua implementação de PFLT_INSTANCE_SETUP_CALLBACK. Executar essas operações pode levar a condições de deadlock.

Quando um driver de minifiltro se registra chamando FltRegisterFilter de sua rotina de DriverEntry, ele pode registrar uma rotina de tipo PFLT_INSTANCE_SETUP_CALLBACK como a rotina de instanceSetupCallback do driver de minifiltro.

Para registrar a rotina InstanceSetupCallback, o driver de minifiltro armazena o endereço de uma rotina de PFLT_INSTANCE_SETUP_CALLBACK de tipo no instanceSetupCallback membro da estrutura FLT_REGISTRATION que o driver de minifiltro passa como o parâmetro de Registro do FltRegisterFilter .

O gerenciador de filtros chama essa rotina na primeira operação depois que um novo volume é montado.

O gerenciador de filtros chama essa rotina para permitir que o driver de minifiltro responda a uma solicitação de anexo automática ou manual. Se essa rotina retornar um código NTSTATUS de erro ou aviso, a instância do driver de minifiltro não será anexada ao volume especificado. Caso contrário, a instância do driver de minifiltro é anexada ao volume especificado.