FltOplockBreakH-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltOplockBreakH-Routine unterbricht CACHE_HANDLE_LEVEL opportunistische Sperren (Oplocks).

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltOplockBreakH(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Parameter

[in] Oplock

Ein undurchsichtiger Oplock-Zeiger für die Datei. Dieser Zeiger muss durch einen vorherigen Aufruf von FltInitializeOplock initialisiert worden sein.

[in] CallbackData

Ein Zeiger auf die Rückrufdatenstruktur (FLT_CALLBACK_DATA) für den E/A-Vorgang.

[in] Flags

Eine Bitmaske für den zugeordneten Datei-E/A-Vorgang. Ein Minifiltertreiber legt Bits fest, um das Verhalten von FltOplockBreakH anzugeben. Der Flags-Parameter verfügt über die folgenden Optionen:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Ermöglicht es einem Oplock-Umbruch, ohne den Vorgang, der den Oplock-Umbruch verursacht hat, zu blockieren oder ausstehen zu müssen.

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Ermöglicht CACHE_HANDLE_LEVEL oplock-Unterbrechungen, unabhängig von der oplock-Taste fortzufahren.

[in, optional] Context

Ein Zeiger auf vom Aufrufer definierte Kontextinformationen, die an die Rückrufroutinen übergeben werden sollen, auf die die Parameter WaitCompletionRoutine und PrePostCallbackDataRoutine verweisen.

[in, optional] WaitCompletionRoutine

Ein Zeiger auf eine vom Anrufer bereitgestellte Rückrufroutine. Wenn ein Oplock-Umbruch ausgeführt wird, wird diese Routine aufgerufen, wenn die Unterbrechung abgeschlossen ist. Dieser Parameter ist optional und kann NULL sein. Wenn es NULL ist, wird der Aufrufer in einen Wartezustand versetzt, bis die Oplock-Umbruch abgeschlossen ist.

Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
    __in PFLT_CALLBACK_DATA CallbackData,
 __in_opt PVOID Context
    );

Diese Routine hat die folgenden Parameter:

CallbackData

Ein Zeiger auf die Rückrufdatenstruktur für den E/A-Vorgang.

Kontext

Ein Kontextinformationszeiger, der im Context-Parameter an FltOplockBreakH übergeben wurde.

[in, optional] PrePostCallbackDataRoutine

Ein Zeiger auf eine vom Anrufer bereitgestellte Rückrufroutine, die aufgerufen werden soll, wenn der E/A-Vorgang geschrieben werden muss. Die Routine wird aufgerufen, bevor das oplock-Paket den IRP aufgibt. Dieser Parameter ist optional und kann NULL sein.

Diese Routine wird wie folgt deklariert:

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
    __in PFLT_CALLBACK_DATA CallbackData,
 __in_opt PVOID Context
      );

Diese Routine hat die folgenden Parameter:

CallbackData

Ein Zeiger auf die Rückrufdatenstruktur für den E/A-Vorgang.

Kontext

Ein Kontextinformationszeiger, der im Context-Parameter an FltOplockBreakH übergeben wurde.

Rückgabewert

FltOplockBreakH gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS-Codes zurück:

Rückgabecode	Beschreibung
FLT_PREOP_COMPLETE	FltOplockBreakH ist ein Poolzuordnungsfehler aufgetreten, oder ein Aufruf der FsRtlOplockBreakH-Funktion hat einen Fehler zurückgegeben. FltOplockBreakH legt den Fehlercode im Statuselement der IO_STATUS_BLOCK-Struktur fest. Die IO_STATUS_BLOCK-Struktur wird im IoStatus-Member der FLT_CALLBACK_DATA Rückrufdatenstruktur angegeben. Der Parameter CallbackData verweist auf diesen FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Es wurde ein Oplock-Umbruch initiiert, der dazu führte, dass der Filter-Manager den E/A-Vorgang in einer Arbeitswarteschlange postete. Der E/A-Vorgang wird durch die Rückrufdaten dargestellt, auf die der CallbackData-Parameter verweist.
FLT_PREOP_SUCCESS_WITH_CALLBACK	Die Rückrufdaten, auf die der CallbackData-Parameter verweist, wurden nicht geschrieben, und der E/A-Vorgang wurde sofort ausgeführt. Beachten Sie, dass, wenn der Aufrufer OPLOCK_FLAG_COMPLETE_IF_OPLOCKED im Flags-Parameter angegeben hat, möglicherweise ein Oplock-Umbruch ausgeführt wird, obwohl der E/A-Vorgang nicht geschrieben wurde. Um zu ermitteln, ob dies der Fall ist, sollte der Aufrufer im Statuselement der IO_STATUS_BLOCK-Struktur nach STATUS_OPLOCK_BREAK_IN_PROGRESS suchen. Die IO_STATUS_BLOCK-Struktur wird im IoStatus-Member der FLT_CALLBACK_DATA Rückrufdatenstruktur angegeben.

Hinweise

Weitere Informationen zu opportunistischen Sperren finden Sie in der Microsoft Windows SDK-Dokumentation.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Die FltOplockBreakH-Routine ist ab Windows 7 verfügbar.
Zielplattform	Universell
Header	fltkernel.h (include Fltkernel.h)
Bibliothek	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL