PFLT_INSTANCE_TEARDOWN_CALLBACK Rückruffunktion (fltkernel.h)

Artikel
02/06/2025

Ein Minifiltertreiber kann zwei Routinen vom Typ PFLT_INSTANCE_TEARDOWN_CALLBACK als InstanceTeardownStartCallback- des Minifiltertreibers registrieren und InstanceTeardownCompleteCallback Routinen.

Syntax

PFLT_INSTANCE_TEARDOWN_CALLBACK PfltInstanceTeardownCallback;

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

Parameter

[in] FltObjects

Zeiger auf eine FLT_RELATED_OBJECTS Struktur, die undurchsichtige Zeiger für die Objekte enthält, die mit dem aktuellen E/A-Vorgang zusammenhängen.

[in] Reason

Flag, das angibt, warum die Minifiltertreiberinstanz heruntergerissen wird. Eine der folgenden:

Flagge	Bedeutung
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	Die Instanz wird getrennt, da eine Benutzermodusanwendung FilterDetach- aufgerufen hat oder eine Kernelmoduskomponente FltDetachVolumeaufgerufen hat.
FLTFL_INSTANCE_TEARDOWN_FILTER_UNLOAD (0x00000002)	Der Minifiltertreiber wird entladen.
FLTFL_INSTANCE_TEARDOWN_MANDATORY_FILTER_UNLOAD (0x00000004)	Der Minifiltertreiber wird entladen.
FLTFL_INSTANCE_TEARDOWN_VOLUME_DISMOUNT (0x00000008)	Bei Festlegung wird die Bereitstellung des Volumes aufgehoben. (Oder das Volume wurde bereits aufgehoben. Oder der Volume-Mount-Vorgang ist fehlgeschlagen. Oder die Minifiltertreiberinstanz oder das Volume wird heruntergerissen. Oder das Dateisystem hat sich als aktives Dateisystem nicht registriert.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	Beim System ist ein unerwarteter interner Fehler aufgetreten.

Rückgabewert

Nichts

Bemerkungen

Wenn sich ein Minifiltertreiber selbst registriert, indem er FltRegisterFilter aus seiner DriverEntry- Routine aufruft, kann er zwei Routinen vom Typ PFLT_INSTANCE_TEARDOWN_CALLBACK als InstanceTeardownStartCallback und InstanceTeardownCompleteCallback-Routinen registrieren. Um diese Rückrufroutinen zu registrieren, speichert der Minifiltertreiber die Adressen der beiden Routinen vom Typ PFLT_INSTANCE_TEARDOWN_CALLBACK im InstanceTeardownStartCallback und InstanceTeardownCompleteCallback Member der FLT_REGISTRATION Struktur, die der Minifiltertreiber als Registration Parameter von FltRegisterFilterübergibt.

Die InstanceTeardownStartCallback und InstanceTeardownCompleteCallback Routinen sind optional und können NULL-sein. Wenn der Minifiltertreiber NULL- für die InstanceTeardownStartCallback- oder InstanceTeardownCompleteCallback-Routine angibt, wird die Instanz immer noch heruntergerissen.

Die InstanceTeardownStartCallback- Routine wird aufgerufen, wenn der Filter-Manager mit dem Abreißen einer Minifiltertreiberinstanz beginnt, damit der Minifiltertreiber alle eingestifteten E/A-Vorgänge abschließen und Zustandsinformationen speichern kann.

Die InstanceTeardownStartCallback- Routine muss:

Rufen Sie FltCompletePendedPreOperation für jeden E/A-Vorgang auf, der in der Preoperationsrückrufroutine des Minifiltertreibers eingestiftet wurde, um den Vorgang abzuschließen oder die Steuerung des Vorgangs an den Filter-Manager zurückzugeben.
Keine neuen E/A-Vorgänge. Wenn der Minifiltertreiber eine Rückrufdatenwarteschlange verwendet, muss er FltCbdqDisable- aufrufen, um ihn zu deaktivieren.
Rufen Sie FltCompletePendedPostOperation für jeden E/A-Vorgang auf, der in der Postoperationsrückrufroutine des Minifiltertreibers eingestiftet wurde, um die Steuerung des Vorgangs an den Filter-Manager zurückzugeben.

Die InstanceTeardownStartCallback Routine kann optional folgendes ausführen, damit der Minifiltertreiber so schnell wie möglich entladen werden kann:

Schließen Sie alle geöffneten Dateien.
Stellen Sie sicher, dass Arbeitsthreads nur das Minimum ausführen, das zum Abschließen der Verarbeitung ausstehender Arbeitsaufgaben erforderlich ist.
Rufen Sie FltCancelIo- auf, um alle E/A-Vorgänge abzubrechen, die vom Minifiltertreiber initiiert wurden.
Beenden Sie die Warteschlange für neue Arbeitsaufgaben.

Sobald die InstanceTeardownStartCallback Routine des Minifiltertreibers aufgerufen wurde, werden die Voroperations- und Postoperationsrückrufroutinen des Minifilters nicht für neue E/A-Vorgänge aufgerufen. Sie können jedoch für E/A-Vorgänge aufgerufen werden, die gestartet wurden, bevor ein Instanz-Abbruch eingeleitet wurde.

Die InstanceTeardownCompleteCallback- Routine wird aufgerufen, wenn der Teardownprozess abgeschlossen ist, damit der Minifiltertreiber geöffnete Dateien schließen und alle anderen erforderlichen Bereinigungsverarbeitungen durchführt.

Die InstanceTeardownCompleteCallback- Routine muss alle Dateien schließen, die vom Minifiltertreiber geöffnet wurden.

Der Filter-Manager ruft die InstanceTeardownCompleteCallback Routine des Minifiltertreibers nur auf, nachdem alle ausstehenden E/A-Vorgänge abgeschlossen oder entwässert wurden.

Warnung

Die InstanceTeardownCompleteCallback- Routine wird nicht aufgerufen, wenn eine der folgenden Bedingungen zutrifft:

Es gibt ausstehende E/A-Vorgänge.
Es gibt alle ausstehenden E/A-Vorgänge, die vom Minifiltertreiber initiiert wurden.

Wenn die Minifiltertreiberinstanz heruntergerissen wird, da der Minifiltertreiber entladen wird, wird der Entladevorgang so lange hängen, bis die InstanceTeardownCompleteCallback- Routine zurückgegeben wird. Um diese Arten von Problemen zu debuggen, sollten Sie die Driver Verifier- auf Ihrem Minifiltertreiber aktivieren. Die Option "Filterüberprüfung" E/A-Überprüfung kann dabei helfen, mögliche Ursachen zu identifizieren, z. B. nichtleasierte Verweise, die verhindern würden, dass der Minifiltertreiber entladen wird. Weitere Informationen finden Sie unter Filterüberprüfung.

Beachten Sie, dass das Verweisen auf die Instanz (durch Aufrufen von FltObjectReference) nicht verhindert, dass die InstanceTeardownCompleteCallback Routine aufgerufen wird.

Der Filter-Manager ruft die InstanceTeardownStartCallback- und InstanceTeardownCompleteCallback Routinen bei IRQL-PASSIVE_LEVEL auf.