FltCheckOplockEx-Funktion (fltkernel.h)
Ein Minifiltertreiber ruft die FltCheckOplockEx-Routine auf, um die Rückrufdatenstruktur für einen IRP-basierten Datei-E/A-Vorgang zu synchronisieren, der den aktuellen oplock-Zustand (Opportunistic Lock) der Datei aufweist.
Syntax
FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
[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ückrufdaten FLT_CALLBACK_DATAStruktur 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 FltCheckOplockEx anzugeben. Der Flags-Parameter verfügt über die folgenden Optionen:
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)
Ermöglicht eine opportunistische Sperrunterbrechung, ohne dass der Vorgang blockiert oder aussteht, der den Oplock-Umbruch verursacht hat.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)
Gibt an, dass FltCheckOplockEx auf der FILE_OBJECT, die dem E/A-Vorgang zugeordnet ist, nur nach einer opportunistischen Sperrtaste suchen soll. Diese E/A-Vorgänge werden durch die Rückrufdaten dargestellt, auf die der CallbackData-Parameter verweist. FltCheckOplockEx muss dann den Schlüssel hinzufügen, wenn er im E/A-Vorgang bereitgestellt wird. Es erfolgt keine andere Oplock-Verarbeitung. Das heißt, es tritt kein opportunistischer Sperrbruch auf.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)
Gibt an, dass FsRtlCheckOplockEx jeden Zustand rückgängig machen soll, der zuvor durch einen Aufruf der FltOplockFsctrl-Routine eingerichtet wurde. FltOplockFsctrl wird aufgerufen, wenn eine IRP_MJ_CREATE Anforderung verarbeitet wird. Diese IRP_MJ_CREATE Anforderung gibt das FILE_OPEN_REQUIRING_OPLOCK-Flag im Parameter create options an. Das flag OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK wird in der Regel bei der endgültigen Verarbeitung einer solchen Erstellungsanforderung verwendet, wenn zuvor ein Fehler aufgetreten ist.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)
Ermöglicht es, alle opportunistischen Sperrunterbrechungen unabhängig von der opportunistischen Sperrtaste fortzusetzen.
[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 Anrufer bereitgestellte Rückrufroutine. Wenn ein Oplock-Umbruch 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 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 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 FltCheckOplockEx ü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 FltCheckOplockEx übergeben wurde.
Rückgabewert
FltCheckOplockEx gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS Codes zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
FltCheckOplockEx ist ein Poolzuordnungsfehler aufgetreten, oder ein Aufruf der FsRtlCheckOplockEx-Funktion hat einen Fehler zurückgegeben. FltCheckOplockEx legt den Fehlercode im Statuselement der IO_STATUS_BLOCK-Struktur des IoStatus-Members der FLT_CALLBACK_DATA Rückrufdatenstruktur fest. Der CallbackData-Parameter verweist auf diese FLT_CALLBACK_DATA-Struktur. |
|
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. |
|
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 des IoStatus-Members der FLT_CALLBACK_DATA Rückrufdatenstruktur nach STATUS_OPLOCK_BREAK_IN_PROGRESS suchen. |
Hinweise
Ein Minifiltertreiber ruft FltCheckOplockEx auf, um einen IRP-basierten E/A-Vorgang mit dem aktuellen Oplock-Zustand einer Datei gemäß den folgenden Bedingungen zu synchronisieren:
Wenn der E/A-Vorgang dazu führt, dass der Oplock unterbrochen wird, wird der Oplock-Umbruch initiiert.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der Oplock-Umbruch abgeschlossen ist, gibt FltCheckOplockEx FLT_PREOP_PENDING zurück und ruft die Rückrufroutine auf, auf die der PrePostCallbackDataRoutine-Parameter verweist.
Wenn ein Minifiltertreiber oplocks verwendet, muss er FltCheckOplockEx aus jeder PFLT_PRE_OPERATION_CALLBACK-Routine (Preoperation Callback) für E/A-Vorgänge aufrufen, die oplock-Unterbrechungen verursachen können. Diese Regel gilt für die folgenden Typen von E/A-Vorgängen, da diese Vorgänge oplock-Unterbrechungen verursachen 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 FltCheckOplockEx innerhalb des in WaitCompletionRoutine angegebenen Rückrufs nicht erneut aufrufen. Dies kann zu einer Deadlockbedingung führen, wenn das oplock-Paket den Abschlussrückruf aufruft, bevor FltCheckOplockEx zurückgibt.
Weitere Informationen zu opportunistischen Sperren finden Sie in der Microsoft Windows SDK-Dokumentation.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Die FltCheckOplockEx-Routine ist ab Windows 7 verfügbar. |
| Zielplattform | Universell |
| Header | fltkernel.h (include Fltkernel.h) |
| Bibliothek | FltMgr.lib |
| IRQL | <= APC_LEVEL |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für