PFLT_INSTANCE_TEARDOWN_CALLBACK Rückruffunktion (fltkernel.h)

Artikel
08/07/2023

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

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 sich auf den aktuellen E/A-Vorgang beziehen.

[in] Reason

Flag, das angibt, warum der Minifiltertreiber instance abgerissen wird. Einer der folgenden:

Flag	Bedeutung
FLTFL_INSTANCE_TEARDOWN_MANUAL (0x00000001)	Die instance wird getrennt, da eine Anwendung im Benutzermodus FilterDetach oder eine Kernelmoduskomponente FltDetachVolume genannt 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)	Wenn festgelegt, wird die Bereitstellung des Volumes aufgehoben. (Oder das Volume wurde bereits aufgehoben. Oder der Volumeeinbindungsvorgang ist fehlgeschlagen. Oder der Minifiltertreiber instance oder das Volume wird abgerissen. Oder das Dateisystem hat sich selbst als aktives Dateisystem nicht registriert.)
FLTFL_INSTANCE_TEARDOWN_INTERNAL_ERROR (0x00000010)	Beim System ist ein unerwarteter interner Fehler aufgetreten.

Rückgabewert

Keine

Bemerkungen

Wenn sich ein Minifiltertreiber durch Aufrufen von FltRegisterFilter über seine DriverEntry-Routine registriert, kann er zwei Routinen vom Typ PFLT_INSTANCE_TEARDOWN_CALLBACK als die Routinen InstanceTeardownStartCallback und InstanceTeardownCompleteCallback des Minifiltertreibers registrieren. Um diese Rückrufroutinen zu registrieren, speichert der Minifiltertreiber die Adressen der beiden Routinen vom Typ PFLT_INSTANCE_TEARDOWN_CALLBACK in den Membern InstanceTeardownStartCallback und InstanceTeardownCompleteCallback der FLT_REGISTRATION Struktur, die der Minifiltertreiber als Registrierungsparameter von FltRegisterFilter übergibt.

Die Routinen InstanceTeardownStartCallback und InstanceTeardownCompleteCallback sind optional und können NULL sein. Wenn der Minifiltertreiber NULL für die Routine InstanceTeardownStartCallback oder InstanceTeardownCompleteCallback angibt, wird die instance weiterhin abgerissen.

Die InstanzTeardownStartCallback-Routine wird aufgerufen, wenn der Filter-Manager mit dem Löschen eines Minifiltertreibers beginnt, instance, damit der Minifiltertreiber alle E/A-Vorgänge ausführen und Zustandsinformationen speichern kann.

Die InstanzTeardownStartCallback-Routine muss:

Rufen Sie FltCompletePendedPreOperation für jeden E/A-Vorgang auf, der in der Preoperation-Rückrufroutine des Minifiltertreibers enthalten war, 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 Postoperation-Rückrufroutine des Minifiltertreibers enthalten war, um die Steuerung des Vorgangs an den Filter-Manager zurückzugeben.

Die InstanzTeardownStartCallback-Routine kann optional die folgenden Aktionen ausführen, damit der Minifiltertreiber so schnell wie möglich entladen wird:

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

Nachdem die InstanceTeardownStartCallback-Routine des Minifiltertreibers aufgerufen wurde, werden die Voroperations- und Postoperationsrückrufroutinen des Minifiltertreibers für keine neuen E/A-Vorgänge aufgerufen. Sie können jedoch für E/A-Vorgänge aufgerufen werden, die gestartet wurden, bevor instance Teardown initiiert wurde.

Die InstanzTeardownCompleteCallback-Routine wird aufgerufen, wenn der Teardownprozess abgeschlossen ist, damit der Minifiltertreiber geöffnete Dateien schließen und alle anderen erforderlichen Bereinigungsvorgänge ausführen kann.

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

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

Warnung

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

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

Wenn der Minifiltertreiber instance abgerissen wird, weil der Minifiltertreiber entladen wird, scheint der Entladevorgang zu hängen, bis die InstanzTeardownCompleteCallback-Routine zurückgegeben wird. Um diese Art von Problemen zu debuggen, sollten Sie die Treiberüberprüfung auf Ihrem Minifiltertreiber aktivieren. Die Option E/A-Überprüfung der Filterüberprüfung kann dabei helfen, mögliche Ursachen wie nicht freigegebene Verweise zu identifizieren, die das Entladen des Minifiltertreibers verhindern. Weitere Informationen finden Sie unter Filter Verifier.

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

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