FsRtlCheckOplockEx-Funktion (ntifs.h)

Artikel
02/29/2024

Die FsRtlCheckOplockEx-Routine synchronisiert den 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 FsRtlInitializeOplock initialisiert worden sein.

[in] Irp

Ein Zeiger auf den 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 FsRtlCheckOplockEx anzugeben. Der Flags-Parameter verfügt über die folgenden Optionen:

Wert	Bedeutung
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Gibt an, dass ein opportunistischer Sperrbruch fortgesetzt werden kann, ohne den Vorgang zu blockieren oder ausstehen zu lassen, der den Oplock-Umbruch verursacht hat.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Unterstützt ab Windows 7. Gibt an, dass FsRtlCheckOplockEx nur auf der FILE_OBJECT, die dem IRP zugeordnet ist, auf den der Irp-Parameter verweist, nur auf einen opportunistischen Sperrschlüssel überprüfen soll. FsRtlCheckOplockEx muss dann den Schlüssel hinzufügen, wenn einer in der IRP angegeben ist. Es erfolgt keine andere Oplockverarbeitung. das heißt, es kommt zu keinem opportunistischen Sperrbruch.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Unterstützt ab Windows 7. Gibt an, dass FsRtlCheckOplockEx jeden Zustand rückgängig machen 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 flag FILE_OPEN_REQUIRING_OPLOCK 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)	Unterstützt ab Windows 7. Gibt an, dass alle opportunistischen Sperrunterbrechungen unabhängig von der opportunistischen Sperrtaste fortgesetzt werden können.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Unterstützt ab Windows 8. Gibt an, dass Oplock dem übergeordneten Verzeichnis (Verzeichnis) der Datei oder des Verzeichnisses zugeordnet ist, an das bzw. das der IRP im Irp-Parameter weitergeleitet wird.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Unterstützt ab Windows 8. Gibt an, dass der in Irp angegebene E/A-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 Flag ist nicht wirksam, wenn Irp kein IRP_MJ_CLEANUP Vorgang ist. Die Angabe dieses Flags kann zu einem opportunistischen Sperrbruch führen.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Unterstützt ab Windows 8. Gibt die Behandlung eines opportunistischen Sperrumbruchs in einem übergeordneten Verzeichnis an, wenn eine Datei oder ein Link in diesem Verzeichnis gelöscht wird. Wenn angegeben, muss dieses Flag 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 auf vom Aufrufer definierte Kontextinformationen, die an die Rückrufroutinen übergeben werden sollen, auf die die Parameter CompletionRoutine und PostIrpRoutine 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 der Wert 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 verfügt über die folgenden Parameter:

Parameter	BESCHREIBUNG
Kontext	Ein Kontextinformationszeiger, der im Context-Parameter an FsRtlCheckOplockEx übergeben wurde.
Irp	Ein Zeiger auf den 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 an eine Arbeitswarteschlange gesendet 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 verfügt über die folgenden Parameter:

Parameter	BESCHREIBUNG
Kontext	Ein Kontextinformationszeiger, der im Context-Parameter an FsRtlCheckOplockEx übergeben wurde.
Irp	Ein Zeiger auf den IRP für den E/A-Vorgang.

Rückgabewert

FsRtlCheckOplockEx gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Code zurück, z. B. einen der folgenden:

Rückgabecode	Beschreibung
STATUS_CANCELLED	Die IRP wurde abgebrochen. STATUS_CANCELLED ist ein Fehlercode.
STATUS_CANNOT_BREAK_OPLOCK	Der Oplock-Umbruch (Opportunistic Lock) 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 gibt einen gewährten Oplock.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Ein opportunistischer Sperrbruch ist im Gange. Die IRP ist eine IRP_MJ_CREATE-Anforderung, und FILE_COMPLETE_IF_OPLOCKED wurde im Parameter create options für den Vorgang angegeben. 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	Ein opportunistischer Sperrbruch wurde initiiert, und die Steuerung 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.

Hinweise

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

Wenn der E/A-Vorgang bewirkt, dass die opportunistische Sperre unterbrochen wird, wird der opportunistische Sperrbruch initiiert.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der opportunistische Sperrumbruch abgeschlossen ist und eine Abschlussroutine in CompletionRoutine angegeben wurde, gibt FsRtlCheckOplockEx STATUS_PENDING zurück und ruft die in PostIrpRoutine angegebene Rückrufroutine auf. Wenn der opportunistische Sperrumbruch bestätigt wurde, wird die Rückrufroutine in CompletionRoutine aufgerufen.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der opportunistische Sperrumbruch abgeschlossen und CompletionRoutine nicht angegeben wurde, wird FsRtlCheckOplockEx erst zurückgegeben, wenn der opportunistische Sperrumbruch bestätigt wurde.

Eine PostIrpRoutine sollte nur angegeben werden, wenn eine CompletionRoutine angegeben wurde.

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

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

Minifilter sollten FltCheckOplockEx anstelle von FsRtlCheckOplockEx aufrufen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL