PFLT_INSTANCE_SETUP_CALLBACK Rückruffunktion (fltkernel.h)

Artikel
09/03/2023

Ein Minifiltertreiber kann eine Routine vom Typ PFLT_INSTANCE_SETUP_CALLBACK als InstanceSetupCallback-Routine des Minifiltertreibers registrieren.

Syntax

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

Parameter

[in] FltObjects

Zeiger auf eine FLT_RELATED_OBJECTS Struktur, die undurchsichtige Zeiger für die Objekte enthält, die sich auf den aktuellen Vorgang beziehen.

[in] Flags

Bitmaske von Flags, die angeben, warum die instance angefügt wird. Dies kann eine oder mehrere der folgenden Optionen sein:

Flag	Bedeutung
FLTFL_INSTANCE_SETUP_AUTOMATIC_ATTACHMENT (0x00000001)	Die instance wird automatisch angefügt. Entweder wurde der Minifiltertreiber gerade geladen und wird an alle vorhandenen Volumes angefügt, oder er wird an ein neu bereitgestelltes Volume angefügt.
FLTFL_INSTANCE_SETUP_MANUAL_ATTACHMENT (0x00000002)	Die instance wird manuell angefügt, weil eine Anwendung im Benutzermodus FilterAttach oder FilterAttachAtAltitude aufgerufen hat oder weil eine Kernelmoduskomponente FltAttachVolume oder FltAttachVolumeAtAltitude aufgerufen hat.
FLTFL_INSTANCE_SETUP_NEWLY_MOUNTED_VOLUME (0x00000004)	Die instance wird automatisch an ein neu bereitgestelltes Volume angefügt.
FLTFL_INSTANCE_SETUP_DETACHED_VOLUME (0x00000008)	Die instance wird an ein getrenntes Volume angefügt. Auf einigen Dateisystemen (z. B. FAT und CDFS, die von einigen Wechselmedienlaufwerken verwendet werden) ist es möglich, ein Volume erneut anfügen, nachdem es getrennt wurde. Ein Volume wird getrennt, wenn es keinen zugeordneten Speicherstapel aufweist. Ein Volume in diesem Zustand ist normalerweise ein nicht eingebundenes Volume, das noch geöffnete Dateien enthält.
FLTFL_INSTANCE_SETUP_DEV_VOLUME (0x00000010)	Die instance wird an ein Volume angefügt, das als Entwicklervolume formatiert ist. Dateisystemfilter können Optimierungen ermöglichen, die nicht erfordern, dass ein Administrator dem Volume auf einem bestimmten Computer vertraut. Verfügbar ab Windows 11, Version 22H2 September Update.
FLTFL_INSTANCE_SETUP_TRUSTED_VOLUME (0x00000020)	Gibt an, dass ein Administrator auf einem bestimmten Computer diesem Volume vertraut und bereit ist, Optimierungen wie das Anfügen von Antivirenfiltern an das Volume zu ermöglichen. Diese Informationen werden in der Registrierung auf einem bestimmten Computer gespeichert. Dies kann von den Dateisystemfiltern verwendet werden, um Optimierungen zu ermöglichen, bei denen ein Administrator dem Volume auf einem bestimmten Computer vertrauen muss. Verfügbar ab Windows 11, Version 22H2 September Update.

[in] VolumeDeviceType

Gerätetyp des Dateisystemvolumes. Dies muss eine der folgenden Ressourcen sein:

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

[in] VolumeFilesystemType

Dateisystemtyp des Volumes. Die möglichen Werte sind in FLT_FILESYSTEM_TYPE aufgeführt.

Rückgabewert

Diese Rückrufroutine gibt STATUS_SUCCESS oder einen NTSTATUS-Wert wie den folgenden zurück:

Rückgabecode	Beschreibung
STATUS_FLT_DO_NOT_ATTACH	Durch die Rückgabe dieses Werts wird verhindert, dass der Minifiltertreiber instance an das angegebene Volume angefügt wird. Dies ist ein Fehlercode.

Hinweise

Hinweis

Führen Sie keine Threadsynchronisierung oder prozessübergreifende Kommunikation in Ihrer PFLT_INSTANCE_SETUP_CALLBACK-Implementierung durch. Das Ausführen solcher Vorgänge kann zu Deadlockbedingungen führen.

Wenn sich ein Minifiltertreiber durch Aufrufen von FltRegisterFilter aus seiner DriverEntry-Routine registriert, kann er eine Routine vom Typ PFLT_INSTANCE_SETUP_CALLBACK als InstanzsetupCallback-Routine des Minifiltertreibers registrieren.

Um die InstanzSetupCallback-Routine zu registrieren, speichert der Minifiltertreiber die Adresse einer Routine vom Typ PFLT_INSTANCE_SETUP_CALLBACK im Member InstanceSetupCallback der FLT_REGISTRATION Struktur, die der Minifiltertreiber als Registrierungsparameter von FltRegisterFilter übergibt.

Der Filter-Manager ruft diese Routine beim ersten Vorgang auf, nachdem ein neues Volume bereitgestellt wurde.

Der Filter-Manager ruft diese Routine auf, damit der Minifiltertreiber auf eine automatische oder manuelle Anlageanforderung reagieren kann. Wenn diese Routine einen Fehler- oder Warnungscode NTSTATUS zurückgibt, wird der Minifiltertreiber instance nicht an das angegebene Volume angefügt. Andernfalls wird der Minifiltertreiber instance an das angegebene Volume angefügt.