PFLT_INSTANCE_SETUP_CALLBACK funzione di callback (fltkernel.h)

Articolo
02/06/2025

Un driver minifiltro può registrare una routine di tipo PFLT_INSTANCE_SETUP_CALLBACK come routine del driver minifilter InstanceSetupCallback routine.

Sintassi

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
)
{...}

Parametri

[in] FltObjects

Puntatore a una struttura FLT_RELATED_OBJECTS che contiene puntatori opachi per gli oggetti correlati all'operazione corrente.

[in] Flags

Maschera di bit di flag che indicano il motivo per cui l'istanza è collegata. Può essere uno o più degli elementi seguenti:

Bandiera	Significato
FLTFL_INSTANCE_SETUP_AUTOMATIC_ATTACHMENT (0x00000001)	L'istanza viene collegata automaticamente. Il driver minifiltro è stato appena caricato ed è collegato a tutti i volumi esistenti oppure è collegato a un nuovo volume montato.
FLTFL_INSTANCE_SETUP_MANUAL_ATTACHMENT (0x00000002)	L'istanza viene collegata manualmente perché un'applicazione in modalità utente ha chiamato FilterAttach o FilterAttachAtAltitudeo perché un componente in modalità kernel ha chiamato FltAttachVolume o FltAttachVolumeAtAltitude
FLTFL_INSTANCE_SETUP_NEWLY_MOUNTED_VOLUME (0x00000004)	L'istanza viene collegata automaticamente a un volume appena montato.
FLTFL_INSTANCE_SETUP_DETACHED_VOLUME (0x00000008)	L'istanza viene collegata a un volume scollegato. È possibile, in alcuni file system (ad esempio FAT e CDFS, usati da alcune unità multimediali rimovibili), per ricollegare un volume dopo che è stato scollegato. Un volume viene scollegato se non ha uno stack di archiviazione associato. Un volume in questo stato è in genere un volume smontato che contiene ancora file aperti.
FLTFL_INSTANCE_SETUP_DEV_VOLUME (0x00000010)	L'istanza viene collegata a un volume formattato come volume per sviluppatori. I filtri del file system possono abilitare le ottimizzazioni che non richiedono che un amministratore consideri attendibile il volume in un determinato computer. Disponibile a partire dall'aggiornamento di settembre di Windows 11, versione 22H2.
FLTFL_INSTANCE_SETUP_TRUSTED_VOLUME (0x00000020)	Indica che un amministratore in un determinato computer ha considerato attendibile questo volume ed è disposto ad abilitare ottimizzazioni come la mancata connessione dei filtri antivirus al volume. Queste informazioni vengono mantenute nel Registro di sistema in un determinato computer. Può essere usato dai filtri del file system per abilitare le ottimizzazioni che richiedono a un amministratore di considerare attendibile il volume in un determinato computer. Disponibile a partire dall'aggiornamento di settembre di Windows 11, versione 22H2.

[in] VolumeDeviceType

Tipo di dispositivo del volume del file system. Deve essere uno dei seguenti:

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

[in] VolumeFilesystemType

Tipo di file system del volume. I valori possibili sono elencati in FLT_FILESYSTEM_TYPE.

Valore restituito

Questa routine di callback restituisce STATUS_SUCCESS o un valore NTSTATUS, ad esempio il seguente:

Codice restituito	Descrizione
STATUS_FLT_DO_NOT_ATTACH	La restituzione di questo valore impedisce l'associazione dell'istanza del driver minifilter al volume specificato. Si tratta di un codice di errore.

Osservazioni

Nota

Non eseguire alcuna sincronizzazione dei thread o comunicazioni tra processi nell'implementazione PFLT_INSTANCE_SETUP_CALLBACK. L'esecuzione di tali operazioni può causare condizioni di deadlock.

Quando un driver minifiltro si registra chiamando FltRegisterFilter dalla routine DriverEntry, può registrare una routine di tipo PFLT_INSTANCE_SETUP_CALLBACK come routine del driver minifilter InstanceSetupCallback routine.

Per registrare la routine InstanceSetupCallback, il driver minifilter archivia l'indirizzo di una routine di tipo PFLT_INSTANCE_SETUP_CALLBACK nel membro InstanceSetupCallback della struttura FLT_REGISTRATION che il driver minifilter passa come parametro Registration di FltRegisterFilter.

Il gestore filtri chiama questa routine alla prima operazione dopo il montaggio di un nuovo volume.

Il gestore filtri chiama questa routine per consentire al driver minifilter di rispondere a una richiesta di allegato automatica o manuale. Se questa routine restituisce un errore o un codice NTSTATUS di avviso, l'istanza del driver minifilter non è collegata al volume specificato. In caso contrario, l'istanza del driver minifilter viene collegata al volume specificato.