FsRtlCheckOplockEx-Funktion (ntifs.h)

Artikel
12/21/2024

Die FsRtlCheckOplockEx Routine synchronisiert das IRP für einen Datei-E/A-Vorgang mit dem aktuellen opportunistischen Sperrzustand (Oplock) der Datei.

Syntax

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

Parameter

[in] Oplock

Ein undurchsichtiger opportunistischer Sperrzeiger für die Datei. Dieser Zeiger muss durch einen vorherigen Aufruf von fsRtlInitializeOplockinitialisiert worden sein.

[in] Irp

Ein Zeiger auf das IRP für den E/A-Vorgang.

[in] Flags

Eine Bitmaske für den zugeordneten Datei-E/A-Vorgang. Ein Dateisystem oder Filtertreiber legt Bits fest, um das Verhalten von FsRtlCheckOplockExanzugeben. Der parameter Flags verfügt über die folgenden Optionen:

Wert	Bedeutung
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Gibt an, dass eine opportunistische Sperrunterbrechung fortgesetzt werden kann, ohne den Vorgang zu blockieren oder ausstehend, der den Oplockbruch verursacht hat.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Wird ab Windows 7 unterstützt. Gibt an, dass FsRtlCheckOplockEx- nur auf einen opportunistischen Sperrschlüssel für die FILE_OBJECT überprüfen soll, die dem IRP zugeordnet ist, auf den der Irp Parameter verweist. FsRtlCheckOplockEx muss dann den Schlüssel hinzufügen, wenn ein Schlüssel im IRP bereitgestellt wird. Keine andere Oplock-Verarbeitung erfolgt; d. h., es tritt keine opportunistische Sperrpause auf.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Wird ab Windows 7 unterstützt. Gibt an, dass FsRtlCheckOplockEx- einen Zustand wiederherstellen soll, der zuvor über einen Aufruf der FsRtlOplockFsctrl Routine eingerichtet wurde. FsRtlOplockFsctrl wird während der Verarbeitung einer IRP_MJ_CREATE Anforderung aufgerufen, die das FILE_OPEN_REQUIRING_OPLOCK Flag im Parameter "Create options" angibt. 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)	Wird ab Windows 7 unterstützt. Gibt an, dass alle opportunistischen Sperrunterbrechungen unabhängig von der opportunistischen Sperre fortgesetzt werden können.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Wird ab Windows 8 unterstützt. Gibt an, dass Oplock- dem übergeordneten (Verzeichnis) der Datei oder des Verzeichnisses zugeordnet ist, an das das IRP im Irp--Parameter weitergeleitet wird.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Wird ab Windows 8 unterstützt. Gibt an, dass der in Irp- angegebene Vorgang ein IRP_MJ_CLEANUP für ein Handle ist, das ursprünglich mit dem in den Erstellungsoptionen festgelegten FILE_DELETE_ON_CLOSE Flag geöffnet wurde. Dieses Kennzeichen hat keine Auswirkung, wenn Irp- kein IRP_MJ_CLEANUP Vorgang ist. Die Angabe dieses Kennzeichens kann zu einem opportunistischen Sperrbruch führen.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Wird ab Windows 8 unterstützt. Gibt die Behandlung eines opportunistischen Sperrumbruchs in einem übergeordneten Verzeichnis beim Löschen einer Datei oder eines Links in diesem Verzeichnis an. Wenn angegeben, muss dieses Kennzeichen mit OPLOCK_FLAG_PARENT_OBJECT kombiniert werden. Dieses Flag muss angegeben werden, wenn das Dateisystem einen Vorgang verarbeitet, der zum Entfernen eines Links oder einer Datei führt.

[in, optional] Context

Ein Zeiger zum Aufrufen definierter Kontextinformationen, die an die Rückrufroutinen übergeben werden sollen, auf die die CompletionRoutine und PostIrpRoutine Parameter verweisen.

[in, optional] CompletionRoutine

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

Diese Routine wird wie folgt deklariert:

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

Diese Routine hat die folgenden Parameter:

Parameter	Beschreibung
Zusammenhang	Ein Kontextinformationspunkt, der im parameter Context an FsRtlCheckOplockExübergeben wurde.
Irp	Ein Zeiger auf das IRP für den E/A-Vorgang.

[in, optional] PostIrpRoutine

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 sein.

Diese Routine wird wie folgt deklariert:

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

Diese Routine hat die folgenden Parameter:

Parameter	Beschreibung
Zusammenhang	Ein Kontextinformationspunkt, der im parameter Context an FsRtlCheckOplockExübergeben wurde.
Irp	Ein Zeiger auf das IRP für den E/A-Vorgang.

Rückgabewert

FsRtlCheckOplockEx gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Code wie einen der folgenden zurück:

Rückgabecode	Beschreibung
STATUS_CANCELLED	Das IRP wurde abgebrochen. STATUS_CANCELLED ist ein Fehlercode.
STATUS_CANNOT_BREAK_OPLOCK	Die opportunistische Sperre (Oplock) kann nicht erreicht werden. Das IRP ist eine IRP_MJ_CREATE Anforderung. FILE_OPEN_REQUIRING_OPLOCK wurde im Parameter "Create options" für den Vorgang angegeben, und es ist ein gewährter Oplock vorhanden.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Eine opportunistische Sperrpause ist im Gange. Das IRP ist eine IRP_MJ_CREATE Anforderung, und FILE_COMPLETE_IF_OPLOCKED im Parameter zum Erstellen von Optionen für den Vorgang angegeben wurde. STATUS_OPLOCK_BREAK_IN_PROGRESS ist ein Erfolgscode, der zurückgegeben wird, wenn OPLOCK_FLAG_COMPLETE_IF_OPLOCKED festgelegt wurde und eine opportunistische Sperre unterbrochen wurde.
STATUS_PENDING	Es wurde eine opportunistische Sperrpause eingeleitet, und die Kontrolle des IRP wurde an das Oplock-Paket übergeben. Wenn "CompletionRoutine" NULL ist, wird diese Routine blockiert, während der Oplock-Umbruch verarbeitet wird, anstatt STATUS_PENDING zurückzugeben. STATUS_PENDING ist ein Erfolgscode.

Bemerkungen

FsRtlCheckOplockEx synchronisiert das IRP für einen E/A-Vorgang mit dem aktuellen opportunistischen Sperrzustand einer Datei gemäß den folgenden Bedingungen:

Wenn die E/A-Operation dazu führt, dass die opportunistische Sperre aufgehoben wird, wird der opportunistische Sperrbruch initiiert.
Wenn der E/A-Vorgang erst fortgesetzt werden kann, wenn die opportunistische Sperrunterbrechung abgeschlossen ist und eine Abschlussroutine in CompletionRoutine angegeben wurde, gibt FsRtlCheckOplockEx STATUS_PENDING zurück und ruft die in PostIrpRoutineangegebene Rückrufroutine auf. Wenn die opportunistische Sperrunterbrechung bestätigt wurde, wird die Rückrufroutine in CompletionRoutine aufgerufen.
Wenn der E/A-Vorgang erst fortgesetzt werden kann, wenn der opportunistische Sperrwechsel abgeschlossen ist und CompletionRoutine nicht angegeben wurde, wird FsRtlCheckOplockEx erst zurückgegeben, wenn der opportunistische Sperrbruch bestätigt wird.

Eine PostIrpRoutine- sollte nur angegeben werden, wenn ein CompletionRoutine- angegeben wurde.

Wenn ein Dateisystem oder Filtertreiber opportunistische Sperren verwendet, muss er FsRtlCheckOplockEx von allen Verteilerroutinen für E/A-Vorgänge aufrufen, die opportunistische Sperrunterbrechungen verursachen können. Diese Regel gilt für die folgenden Typen von E/A-Vorgängen, da diese Vorgänge opportunistische Sperrunterbrechungen 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

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

Minifilter sollten FltCheckOplockEx- anstelle von FsRtlCheckOplockExaufrufen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	<= APC_LEVEL