PFLT_INSTANCE_TEARDOWN_CALLBACK funzione di callback (fltkernel.h)

Articolo
02/06/2025

Un driver minifilter può registrare due routine di tipo PFLT_INSTANCE_TEARDOWN_CALLBACK come routine del driver minifilter InstanceTeardownStartCallback e InstanceTeardownCompleteCallback routine.

Sintassi

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

void PfltInstanceTeardownCallback(
  [in] PCFLT_RELATED_OBJECTS FltObjects,
  [in] FLT_INSTANCE_TEARDOWN_FLAGS Reason
)
{...}

Parametri

[in] FltObjects

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

[in] Reason

Flag che indica il motivo per cui l'istanza del driver minifiltro viene distrutta. Uno dei seguenti:

Bandiera	Significato
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	L'istanza viene scollegata perché un'applicazione in modalità utente ha chiamato FilterDetach o un componente in modalità kernel ha chiamato FltDetachVolume.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	Il driver minifiltro viene scaricato.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	Il driver minifiltro viene scaricato.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	Se impostato, il volume viene smontato. Oppure il volume è già stato smontato. In alternativa, l'operazione di montaggio del volume non è riuscita. Oppure l'istanza del driver minifilter o il volume viene eliminato. Oppure il file system annulla la registrazione come file system attivo.
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	Il sistema ha riscontrato un errore interno imprevisto.

Valore restituito

Nessuno

Osservazioni

Quando un driver minifiltro si registra chiamando FltRegisterFilter dalla routine DriverEntry, può registrare due routine di tipo PFLT_INSTANCE_TEARDOWN_CALLBACK come routine del driver minifilter InstanceTeardownStartCallback e InstanceTeardownCompleteCallback. Per registrare queste routine di callback, il driver minifilter archivia gli indirizzi delle due routine di tipo PFLT_INSTANCE_TEARDOWN_CALLBACK nel InstanceTeardownStartCallback e InstanceTeardownCompleteCallback membri della struttura FLT_REGISTRATION che il driver minifiltro passa come parametro Registration di FltRegisterFilter.

Le routine InstanceTeardownStartCallback e InstanceTeardownCompleteCallback sono facoltative e possono essere NULL. Se il driver minifilter specifica NULL per la routine di InstanceTeardownStartCallback o InstanceTeardownCompleteCallback, l'istanza viene comunque distrutta.

La routine InstanceTeardownStartCallback viene chiamata quando la gestione filtri avvia l'disinstallazione di un'istanza del driver minifiltro per consentire al driver minifiltro di completare le operazioni di I/O con penna e salvare le informazioni sullo stato.

La routine InstanceTeardownStartCallback:

Chiamare FltCompletePendedPreOperation per ogni operazione di I/O pended nella routine di callback del driver minifilter per completare l'operazione o restituire il controllo dell'operazione al gestore filtri.
Non è stata creata alcuna nuova operazione di I/O. Se il driver minifilter usa una coda di dati di callback, deve chiamare FltCbdqDisable per disabilitarla.
Chiamare FltCompletePendedPostOperation per ogni operazione di I/O inserita nella routine di callback del driver minifilter per restituire il controllo dell'operazione al gestore filtri.

La routine InstanceTeardownStartCallback può facoltativamente eseguire le operazioni seguenti per consentire al driver minifilter di scaricare il più rapidamente possibile:

Chiudere tutti i file aperti.
Assicurarsi che i thread di lavoro eseguano solo il minimo necessario per completare l'elaborazione di elementi di lavoro in sospeso.
Chiamare FltCancelIo per annullare le operazioni di I/O avviate dal driver minifiltro.
Interrompere l'accodamento di nuovi elementi di lavoro.

Quando viene chiamata la routine InstanceTeardownStartCallback del driver minifilter, le routine di callback e la preoperazione del driver minifilter non vengono chiamate per le nuove operazioni di I/O. Tuttavia, possono essere chiamati per le operazioni di I/O avviate prima dell'avvio dell'istanza di disinstallazione.

La routine InstanceTeardownCompleteCallback viene chiamata al completamento del processo di disinstallazione per consentire al driver minifilter di chiudere i file aperti ed eseguire qualsiasi altra elaborazione di pulizia necessaria.

La routine InstanceTeardownCompleteCallback deve chiudere tutti i file aperti dal driver minifilter.

Gestione filtri chiama il driver minifilter InstanceTeardownCompleteCallback routine solo dopo che tutte le operazioni di I/O in sospeso sono state completate o svuotate.

Avvertimento

La routine InstanceTeardownCompleteCallback non verrà chiamata se si verifica una delle condizioni seguenti:

Esistono operazioni di I/O pended in sospeso.
Esistono operazioni di I/O in sospeso avviate dal driver minifiltro.

Se l'istanza del driver minifilter viene annullata perché il driver minifilter viene scaricato, l'operazione di scaricamento sembra bloccarsi fino a quando non viene restituita la routine InstanceTeardownCompleteCallback. Per eseguire il debug di questi tipi di problemi, è necessario abilitare il Driver Verifier nel driver minifiltro. L'opzione Verifica filtro verifica I/O può aiutare a identificare possibili cause, ad esempio riferimenti non rilasciati, che impediscono lo scaricamento del driver minifiltro. Per altre informazioni, vedere Filter Verifier.

Si noti che il riferimento all'istanza (chiamando FltObjectReference) non impedisce la chiamata alla routine InstanceTeardownCompleteCallback.

Gestione filtri chiama le routine InstanceTeardownStartCallback e InstanceTeardownCompleteCallback in irQL PASSIVE_LEVEL.