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 opportunistischen Sperrzustand (Oplock) 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 Oplockzeiger 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 FltCheckOplockExanzugeben. Der parameter Flags verfügt über die folgenden Optionen:
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)
Ermöglicht es einem opportunistischen Sperrbruch, den Vorgang fortzusetzen, ohne den Vorgang zu blockieren oder ausstehend, der den Oplockbruch verursacht hat.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)
Gibt an, dass FltCheckOplockEx- nur auf einen opportunistischen Sperrschlüssel für die FILE_OBJECT überprüfen soll, die dem E/A-Vorgang zugeordnet ist. 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 ein Schlüssel im E/A-Vorgang bereitgestellt wird. Keine andere Oplock-Verarbeitung erfolgt; d. h., es tritt keine opportunistische Sperrpause auf.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)
Gibt an, dass FsRtlCheckOplockEx- einen Zustand wiederherstellen soll, der zuvor über 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 OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK-Flag 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 allen opportunistischen Sperrunterbrechungen, unabhängig von der opportunistischen Sperrtaste fortzufahren.
[in, optional] Context
Ein Zeiger auf aufruferdefinierte Kontextinformationen, die an die Rückrufroutinen übergeben werden sollen, die WaitCompletionRoutine und PrePostCallbackDataRoutine verweisen. 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-werden. Wenn es 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 hat die folgenden Parameter:
CallbackData
Ein Zeiger auf die Rückrufdatenstruktur für den E/A-Vorgang.
Beachten Sie, dass beim Aufrufen der WaitCompleteRoutine- möglicherweise die IoStatus-Unterstruktur mit einem Fehlerstatus (z. B. STATUS_CANCELLED) ausgefüllt wird. Sie sollten diesen Status prüfen und entsprechend reagieren.
Zusammenhang
Ein Kontextinformationspunkt, der im parameter Context 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 in eine Arbeitswarteschlange gepostet wird. Dieser Parameter ist optional und kann NULL-werden.
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.
Zusammenhang
Ein Kontextinformationspunkt, der im parameter Context an FltCheckOplockExübergeben wurde.
Rückgabewert
FltCheckOplockEx gibt einen der folgenden FLT_PREOP_CALLBACK_STATUS Codes zurück:
| Rückgabecode | Beschreibung |
|---|---|
|
FltCheckOplockEx ein Poolzuordnungsfehler aufgetreten ist, oder ein Aufruf der FsRtlCheckOplockEx--Funktion hat einen Fehler zurückgegeben. FltCheckOplockEx legt den Fehlercode im Status Member der IO_STATUS_BLOCK Struktur des IoStatus Member der FLT_CALLBACK_DATA Rückrufdatenstruktur fest. Der parameter CallbackData verweist auf diese FLT_CALLBACK_DATA Struktur. |
|
Es wurde eine Oplockunterbrechung initiiert, was dazu führte, dass der Filter-Manager den E/A-Vorgang in eine Arbeitswarteschlange einfügte. 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, wurde nicht mit Stift versehen, und der E/A-Vorgang wurde sofort ausgeführt. Beachten Sie folgendes: Wenn der Aufrufer OPLOCK_FLAG_COMPLETE_IF_OPLOCKED im parameter Flags angegeben hat, wird möglicherweise ein Oplock-Umbruch ausgeführt, obwohl der E/A-Vorgang nicht durchgestiftet wurde. Um festzustellen, ob dies die Situation ist, sollte der Aufrufer im Status- Mitglied der IO_STATUS_BLOCK Struktur des IoStatus Member der FLT_CALLBACK_DATA Rückrufdatenstruktur nach STATUS_OPLOCK_BREAK_IN_PROGRESS suchen. |
Bemerkungen
Ein Minifiltertreiber ruft FltCheckOplockEx auf, um einen IRP-basierten E/A-Vorgang mit dem aktuellen Oplockstatus einer Datei gemäß den folgenden Bedingungen zu synchronisieren:
Wenn der E/A-Vorgang dazu führt, dass der Oplock abgebrochen wird, wird der Oplock-Umbruch initiiert.
Wenn der E/A-Vorgang erst fortgesetzt werden kann, wenn der Oplock-Umbruch abgeschlossen ist, gibt FltCheckOplockEx FLT_PREOP_PENDING zurück und ruft die Rückrufroutine auf, auf die die PrePostCallbackDataRoutine Parameter verweist.
Wenn ein Minifiltertreiber Oplocks verwendet, muss er FltCheckOplockEx- aus jeder Voraboperationsrückrufroutine (PFLT_PRE_OPERATION_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 eine IRP-basierte E/A-Operation sein. Um festzustellen, ob eine bestimmte Rückrufdatenstruktur einen IRP-basierten E/A-Vorgang darstellt, verwenden Sie das FLT_IS_IRP_OPERATION Makro.
Minifilter dürfen FltCheckOplock Ex nicht erneut innerhalb des in WaitCompletionRoutineangegebenen Rückruf aufrufen. Dies kann zu einer Deadlock-Bedingung 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 |
|---|---|
| mindestens unterstützte Client- | Die FltCheckOplockEx-Routine ist ab Windows 7 verfügbar. |
| Zielplattform- | Universal |
| Header- | fltkernel.h (include Fltkernel.h) |
| Library | FltMgr.lib |
| IRQL- | <= APC_LEVEL |