PFLT_INSTANCE_SETUP_CALLBACK Rückruffunktion (fltkernel.h)

2025-02-06

Ein Minifiltertreiber kann eine Routine vom Typ PFLT_INSTANCE_SETUP_CALLBACK als InstanceSetupCall back-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 mit dem aktuellen Vorgang zusammenhängen.

[in] Flags

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

Flagge	Bedeutung
FLTFL_INSTANCE_SETUP_AUTOMATIC_ATTACHMENT (0x00000001)	Die Instanz 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 Instanz wird manuell angefügt, da eine Benutzermodusanwendung FilterAttach oder FilterAttachAtAltitudeaufgerufen hat oder weil eine Kernelmoduskomponente FltAttachVolume oder FltAttachVolumeAtAltitude
FLTFL_INSTANCE_SETUP_NEWLY_MOUNTED_VOLUME (0x00000004)	Die Instanz wird automatisch an ein neu bereitgestelltes Volume angefügt.
FLTFL_INSTANCE_SETUP_DETACHED_VOLUME (0x00000008)	Die Instanz 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 nach dem Trennen erneut anzufügen. Ein Volume wird getrennt, wenn es keinen zugeordneten Speicherstapel aufweist. Ein Volume in diesem Zustand ist in der Regel ein nicht gemountetes Volume, das weiterhin geöffnete Dateien enthält.
FLTFL_INSTANCE_SETUP_DEV_VOLUME (0x00000010)	Die Instanz wird an ein Volume angefügt, das als Entwicklervolume formatiert ist. Dateisystemfilter können Optimierungen aktivieren, für die kein Administrator das Volume auf einem bestimmten Computer als vertrauenswürdig festlegen muss. Verfügbar ab Windows 11, Version 22H2 September Update.
FLTFL_INSTANCE_SETUP_TRUSTED_VOLUME (0x00000020)	Gibt an, dass ein Administrator auf einem bestimmten Computer dieses Volume als vertrauenswürdig eingestuft hat 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, für die ein Administrator das Volume auf einem bestimmten Computer als vertrauenswürdig festlegen muss. Verfügbar ab Windows 11, Version 22H2 September Update.

[in] VolumeDeviceType

Gerätetyp des Dateisystemvolumes. Muss eine der folgenden Werte sein:

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

[in] VolumeFilesystemType

Dateisystemtyp des Volumes. Die möglichen Werte werden in FLT_FILESYSTEM_TYPEaufgefü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 zurückgeben dieses Werts wird verhindert, dass die Minifiltertreiberinstanz an das angegebene Volume angefügt wird. Dies ist ein Fehlercode.

Bemerkungen

Anmerkung

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

Wenn sich ein Minifiltertreiber selbst registriert, indem er FltRegisterFilter aus seiner DriverEntry Routine aufruft, kann er eine Routine vom Typ PFLT_INSTANCE_SETUP_CALLBACK als InstanceSetupCallback- Routine des Minifiltertreibers registrieren.

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

Der Filter-Manager ruft diese Routine für den ersten Vorgang auf, nachdem ein neues Volume bereitgestellt wurde.

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