FltCheckOplock-Funktion (fltkernel.h)

Artikel
02/29/2024

Ein Minifiltertreiber ruft FltCheckOplock auf, um die Rückrufdatenstruktur für einen IRP-basierten Datei-E/A-Vorgang mit dem aktuellen opportunistischen Sperrzustand (Oplock) der Datei zu synchronisieren.

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [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, optional] Context

Ein Zeiger auf vom Aufrufer definierte Kontextinformationen, die an die Rückrufroutinen übergeben werden sollen, auf die WaitCompletionRoutine und PrePostCallbackDataRoutine zeigen. Der Filter-Manager behandelt diese Informationen als undurchsichtig.

[in, optional] WaitCompletionRoutine

Ein Zeiger auf eine vom Aufrufer bereitgestellte Rückrufroutine. Wenn eine Oplockunterbrechung ausgeführt wird, ruft der Filter-Manager diese Routine auf, wenn der Oplock-Umbruch 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 PVOID Context
      );

Diese Routine verfügt über die folgenden Parameter:

CallbackData

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

Kontext

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

[in, optional] PrePostCallbackDataRoutine

Ein Zeiger auf eine vom Anrufer bereitgestellte Rückrufroutine, die aufgerufen werden soll, wenn der E/A-Vorgang an eine Arbeitswarteschlange gesendet wird. 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 PVOID Context
      );

CallbackData

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

Kontext

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

Rückgabewert

FltCheckOplock gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS Codes zurück:

Rückgabecode	Beschreibung
FLT_PREOP_COMPLETE	Bei FltCheckOplock ist ein Poolzuordnungsfehler aufgetreten, oder ein Aufruf der FsRtlCheckOplock-Funktion hat einen Fehler zurückgegeben. FltCheckOplock legt den Fehlercode im Status-Element der IO_STATUS_BLOCK-Struktur des IoStatus-Elements der FLT_CALLBACK_DATA Rückrufdatenstruktur fest. 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	Der E/A-Vorgang wurde sofort ausgeführt. Beachten Sie, dass, wenn es sich bei diesem Vorgang um einen Erstellungsvorgang handelt, der FILE_COMPLETE_IF_OPLOCKED im Create-options-Parameter angegeben hat, möglicherweise eine Oplockunterbrechung ausgeführt wird, obwohl der Vorgang sofort ausgeführt wurde. Um festzustellen, ob dies der Fall ist, sollte der Aufrufer die status im Status-Member der IO_STATUS_BLOCK-Struktur des IoStatus-Elements der FLT_CALLBACK_DATA Rückrufdatenstruktur überprüfen.

Hinweise

Ein Minifiltertreiber ruft FltCheckOplock auf, um einen IRP-basierten E/A-Vorgang mit dem aktuellen Oplockzustand einer Datei gemäß den folgenden Bedingungen zu synchronisieren:

Wenn der E/A-Vorgang dazu führt, dass der Oplock unterbrochen wird, wird die Oplockunterbrechung initiiert.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der Oplock-Umbruch abgeschlossen ist, gibt FltCheckOplock FLT_PREOP_PENDING zurück und ruft die Rückrufroutine auf, auf die der Parameter PrePostCallbackDataRoutine verweist.

Wenn ein Minifiltertreiber oplocks verwendet, muss er FltCheckOplock aus allen PFLT_PRE_OPERATION_CALLBACK-Routinen (Preoperation Callback) für E/A-Vorgänge aufrufen, die zu Oplockunterbrechungen führen können. Diese Regel gilt für die folgenden E/A-Vorgänge, da diese Vorgänge zu Oplockunterbrechungen führen können:

IRP_MJ_CLEANUP

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL

IRP_MJ_FLUSH_BUFFERS

IRP_MJ_LOCK_CONTROL

IRP_MJ_READ

IRP_MJ_SET_INFORMATION

IRP_MJ_WRITE

Der E/A-Vorgang muss ein IRP-basierter E/A-Vorgang sein. Verwenden Sie das Makro FLT_IS_IRP_OPERATION , um zu bestimmen, ob eine bestimmte Rückrufdatenstruktur einen IRP-basierten E/A-Vorgang darstellt.

Minifilter dürfen FltCheckOplock nicht innerhalb des in WaitCompletionRoutine angegebenen Rückrufs erneut aufrufen. Dies kann zu einer Deadlockbedingung führen, wenn das Oplock-Paket den Abschlussrückruf aufruft, bevor FltCheckOplock zurückgibt.

Ausführliche Informationen zu opportunistischen Sperren finden Sie in der Dokumentation zu Microsoft Windows SDK.