FsRtlCheckOplockEx2-Funktion (ntifs.h)

Artikel
12/20/2024

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

Syntax

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

Parameter

[in] Oplock

Zeigen Sie auf die undurchsichtige Oplockstruktur für die Datei. Dieser Zeiger muss durch einen vorherigen Aufruf von fsRtlInitializeOplockinitialisiert worden sein.

[in] Irp

Zeiger auf das IRP, das den angeforderten E/A-Vorgang deklariert.

[in] Flags

Eine Bitmaske für den zugeordneten Datei-E/A-Vorgang. Ein Dateisystem oder Filtertreiber legt Bits fest, um das Verhalten von FsRtlCheckOplockEx2anzugeben. Flags hat die folgenden Optionen:

Flag-Wert	Bedeutung
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Gibt an, dass ein Oplock-Unterbrechung fortgesetzt werden kann, ohne den Vorgang zu blockieren oder ausstehend, der den Oplock-Unterbrechung verursacht hat.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Gibt an, dass FsRtlCheckOplockEx2- nur auf einen Oplock-Schlüssel für die FILE_OBJECT überprüfen soll, die dem IRP zugeordnet ist, auf den der Irp Parameter verweist. FsRtlCheckOplockEx2- 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 Oplockunterbrechung auf. Wird ab Windows 7 unterstützt.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Gibt an, dass FsRtlCheckOplockEx2- 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. Wird ab Windows 7 unterstützt.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Gibt an, dass alle Oplock-Unterbrechungen unabhängig von der Oplock-Taste fortgesetzt werden können. Wird ab Windows 7 unterstützt.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Gibt an, dass Oplock- dem übergeordneten (Verzeichnis) der Datei oder des Verzeichnisses zugeordnet ist, an das das IRP im Irp--Parameter weitergeleitet wird. Wird ab Windows 8 unterstützt.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	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 Oplock-Unterbrechung führen. Wird ab Windows 8 unterstützt.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Gibt die Behandlung eines Oplock-Umbruchs für ein übergeordnetes 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. Wird ab Windows 8 unterstützt.

[in] FlagsEx2

Reserviert; muss auf Null festgelegt werden.

[in, optional] CompletionRoutineContext

Zeiger auf aufruferdefinierte Kontextinformationen, die an die Rückrufroutine übergeben werden sollen, auf die der CompletionRoutine Parameter verweist. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] CompletionRoutine

Zeiger auf eine vom Aufrufer bereitgestellte Rückrufroutine. Wenn eine Oplockunterbrechung ausgeführt wird, wird diese Routine aufgerufen, wenn die Unterbrechung abgeschlossen ist. Dieser Parameter ist optional und kann NULL-werden. Wenn es NULL-ist, FsRtlCheckOpLockEx2 synchron ausgeführt wird, wird der Aufrufer in einen Wartezustand versetzt, bis der Oplock-Umbruch abgeschlossen ist.

CompletionRoutine wird wie folgt deklariert:

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

CompletionRoutine hat die folgenden Parameter:

Kontext-: Ein Kontextinformationspunkt, der im parameter Context an FsRtlCheckOplockEx2übergeben wurde.
Irp-: Ein Zeiger auf das IRP für den E/A-Vorgang.

[in, optional] PostIrpRoutine

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.

PostIrpRoutine wird wie folgt deklariert:

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

PostIrpRoutine hat die folgenden Parameter:

Context, bei dem es sich um einen Kontextinformationspunkt handelt, der im parameter Context an FsRtlCheckOplockEx2übergeben wurde.
Irp-: Ein Zeiger auf das IRP für den E/A-Vorgang.

[in] Timeout

Wenn keine Null ist, wird ein Timeout (in Millisekunden) angegeben, das auf ein Ereignis wartet, mit dem der Thread des Aufrufers blockiert wird, um auf den Abschluss der Oplock-Unterbrechung zu warten. Dieser Wert wird ignoriert, es sei denn, beide der folgenden Bedingungen sind wahr: CompletionRoutine ist NULL und NotifyRoutine ist nicht NULL.

[in, optional] NotifyContext

Zeiger auf eine OPLOCK_NOTIFY_PARAMS Struktur, die an die Rückrufroutine übergeben werden soll, auf die die NotifyRoutine Parameter verweist. Dieser Parameter ist optional und kann NULL-werden.

[in, optional] NotifyRoutine

Zeigen Sie auf eine vom Anrufer bereitgestellte Rückrufroutine, die für die Oplock-Statusbenachrichtigung aufgerufen werden soll. Dieser Parameter ist optional und kann NULL-werden.

NotifyRoutine wird wie folgt deklariert:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine hat die folgenden Parameter:

NotifyParams, die als NotifyContext-parameter festgelegt ist, der an FsRtlCheckOplockEx2übergeben wird.

Rückgabewert

FsRtlCheckOplockEx2 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	Der Oplockbruch 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 Oplockpause 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 ein Oplock unterbrochen wurde.
STATUS_PENDING	Es wird eine Oplockunterbrechung ausgeführt, und die Kontrolle über das IRP wurde an das Oplock-Paket übergeben. Wenn CompletionRoutineNULL-ist, FsRtlCheckOplockEx2 Blöcke, während der Oplock-Umbruch verarbeitet wird, anstatt STATUS_PENDING zurückzugeben. STATUS_PENDING ist ein Erfolgscode.

Bemerkungen

Minifilter sollten FltCheckOplockEx- anstelle von FsRtlCheckOplockEx2aufrufen.

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

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 und eine Abschlussroutine in CompletionRoutine angegeben wurde, gibt FsRtlCheckOplockEx2 STATUS_PENDING zurück und ruft die in PostIrpRoutineangegebene Rückrufroutine auf. Wenn der Oplock-Umbruch bestätigt wurde, wird die Rückrufroutine in CompletionRoutine aufgerufen.
Wenn der E/A-Vorgang erst fortgesetzt werden kann, wenn der Oplock-Umbruch abgeschlossen ist und CompletionRoutine- nicht angegeben wurde, wird der Thread des Aufrufers blockiert und FsRtlCheckOplockEx2 nur zurückgegeben, wenn der Oplock-Umbruch abgeschlossen ist.

Wenn der Thread des Aufrufers blockiert wird und NotifyRoutine nicht NULL-ist, wird NotifyRoutine aus irgendeinem oder allen der folgenden Gründe aufgerufen, die in NotifyParamsfestgelegt werden:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

Der Aufruf von NotifyRoutine aus einem der oben genannten Gründe tritt nur auf, wenn CompletionRoutine- NULL ist und es erforderlich ist, den Thread des Aufrufers zu blockieren, um auf den Abschluss der Unterbrechung zu warten.

Wenn NotifyRoutine aus gründen der OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT aufgerufen wird, wird sie immer aus Gründen aufgerufen, OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED, wenn die Wartezeit aus irgendeinem Grund beendet/abgeschlossen wird (dies kann nie sein).

FsRtlCheckOplockEx2 ignoriert die OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT und OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED Statuscodes, die von NotifyRoutinezurückgegeben werden.

Eine PostIrpRoutine- sollte nur angegeben werden, wenn ein CompletionRoutine- angegeben wurde. Wenn PostIrpRoutine nicht NULL-ist, wird sie aufgerufen, bevor etwas in die wartenden Irp-Warteschlange eingereiht wird.

Wenn das OPLOCK_FLAG_PARENT_OBJECT Flag in Flagsangegeben wird, wird FsRtlCheckOplockEx2 bedingungslos alle vorhandenen übergeordneten Oplocks unterbrechen; d. h., der hauptcode im Irp wird nicht berücksichtigt.

Wenn ein Dateisystem Oplocks verwendet, muss es FsRtlCheckOplockEx2- von allen Verteilerroutinen 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: