FltOplockBreakToNoneEx-Funktion (fltkernel.h)

Artikel
02/26/2024

Die FltOplockBreakToNoneEx-Routine bricht alle opportunistischen Sperren (Oplocks) sofort ohne Rücksicht auf einen Oplock-Schlüssel.

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltOplockBreakToNoneEx(
  [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 Oplockzeiger 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 FltOplockBreakToNoneEx anzugeben. Der Flags-Parameter verfügt über die folgenden Optionen:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Ermöglicht das Fortsetzen einer Oplockunterbrechung, ohne den Vorgang zu blockieren oder ausstehen zu müssen, der den Oplock-Umbruch verursacht hat. In der Regel wird dieses Flag nur verwendet, wenn der E/A-Vorgang, der durch die Rückrufdaten dargestellt wird, auf die der CallbackData-Parameter verweist, ein IRP_MJ_CREATE Vorgang ist.

[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 Aufrufer bereitgestellte Rückrufroutine. Wenn eine Oplockunterbrechung ausgeführt wird, wird diese Routine aufgerufen, wenn die Unterbrechung abgeschlossen ist. Dieser Parameter ist optional und kann NULL sein. Wenn null ist, wird der Aufrufer in einen Wartezustand versetzt, bis der 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 verfügt über die folgenden Parameter:

CallbackData

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

Kontext

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

[in, optional] PrePostCallbackDataRoutine

Ein Zeiger auf eine vom Aufrufer bereitgestellte Rückrufroutine, die aufgerufen werden soll, wenn der E/A-Vorgang mit dem Stift versehen werden soll. Die Routine wird aufgerufen, bevor das oplock-Paket den IRP-Stift angibt. 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 verfügt über die folgenden Parameter:

CallbackData

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

Kontext

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

Rückgabewert

FltOplockBreakToNoneEx gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS Codes zurück:

Rückgabecode	Beschreibung
FLT_PREOP_COMPLETE	FltOplockBreakToNoneEx ist ein Poolzuordnungsfehler aufgetreten, oder ein Aufruf der FsRtlOplockBreakToNoneEx-Funktion hat einen Fehler zurückgegeben. FltOplockBreakToNoneEx legt den Fehlercode im Status-Element der IO_STATUS_BLOCK-Struktur fest. Die IO_STATUS_BLOCK-Struktur wird im IoStatus-Element der FLT_CALLBACK_DATA Rückrufdatenstruktur angegeben. Der Parameter CallbackData verweist auf diesen FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Es wurde eine Oplockunterbrechung initiiert, die 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 Parameter CallbackData verweist, wurden nicht mit Stift versehen, 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 tatsächlich ein Oplock-Umbruch ausgeführt wird, obwohl der E/A-Vorgang nicht mit Stift versehen wurde. Um festzustellen, ob dies der Fall ist, sollte der Aufrufer im Status-Member der IO_STATUS_BLOCK-Struktur nach STATUS_OPLOCK_BREAK_IN_PROGRESS suchen. Die IO_STATUS_BLOCK-Struktur wird im IoStatus-Element der FLT_CALLBACK_DATA Rückrufdatenstruktur angegeben.

Hinweise

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

Anforderungen

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