FsRtlCheckOplockEx2-Funktion (ntifs.h)

Artikel
02/29/2024

FsRtlCheckOplockEx2 synchronisiert das IRP für einen Datei-E/A-Vorgang mit dem aktuellen oplock-Zustand (opportunistic lock) 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

Zeiger auf die undurchsichtige Oplockstruktur für die Datei. Dieser Zeiger muss durch einen vorherigen Aufruf von FsRtlInitializeOplock initialisiert worden sein.

[in] Irp

Zeiger auf den IRP, der 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 FsRtlCheckOplockEx2 anzugeben. Flags verfügt über die folgenden Optionen:

Flagwert	Bedeutung
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Gibt an, dass ein Oplock-Break 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)	Gibt an, dass FsRtlCheckOplockEx2 in der FILE_OBJECT, die dem IRP zugeordnet ist, auf den der Irp-Parameter verweist, nur auf einen Oplock-Schlüssel überprüfen soll. FsRtlCheckOplockEx2 muss dann den Schlüssel hinzufügen, wenn er im IRP angegeben ist. Es erfolgt keine andere Oplockverarbeitung. Das heißt, es tritt kein Oplock-Umbruch auf. Unterstützt ab Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Gibt an, dass FsRtlCheckOplockEx2 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. Unterstützt ab Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Gibt an, dass alle Oplockunterbrechungen unabhängig von der Oplocktaste fortgesetzt werden können. Unterstützt ab Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	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. Unterstützt ab Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	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 Oplock-Umbruch führen. Unterstützt ab Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Gibt die Behandlung eines Oplock-Umbruchs 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. Unterstützt ab Windows 8.

[in] FlagsEx2

Reserviert; muss auf 0 (null) festgelegt werden.

[in, optional] CompletionRoutineContext

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

[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 sein. Wenn es NULL ist, wird FsRtlCheckOpLockEx2 synchron ausgeführt und versetzt den Aufrufer in einen Wartezustand, bis der Oplock-Umbruch abgeschlossen ist.

CompletionRoutine wird wie folgt deklariert:

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

CompletionRoutine verfügt über die folgenden Parameter:

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

[in, optional] PostIrpRoutine

Zeiger auf eine vom Aufrufer 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.

PostIrpRoutine wird wie folgt deklariert:

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

PostIrpRoutine verfügt über die folgenden Parameter:

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

[in] Timeout

Gibt ein Timeout (in Millisekunden) an, das auf ein Ereignis wartet, das verwendet wird, um den Thread des Aufrufers zu blockieren, um auf den Abschluss der Oplockunterbrechung zu warten. Dieser Wert wird ignoriert, es sei denn, die beiden folgenden Bedingungen sind erfüllt: 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 der NotifyRoutine-Parameter verweist. Dieser Parameter ist optional und kann NULL sein.

[in, optional] NotifyRoutine

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

NotifyRoutine wird wie folgt deklariert:

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

NotifyRoutine verfügt über die folgenden Parameter:

NotifyParams, der auf den NotifyContext-Parameter festgelegt ist, der an FsRtlCheckOplockEx2 übergeben wird.

Rückgabewert

FsRtlCheckOplockEx2 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 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 Oplock-Break 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 ein Oplock unterbrochen wurde.
STATUS_PENDING	Ein Oplock-Break ist im Gange, und die Kontrolle über das IRP wurde an das oplock-Paket übergeben. Wenn CompletionRoutineNULL ist, blockiert FsRtlCheckOplockEx2 , während der Oplock-Umbruch verarbeitet wird, anstatt STATUS_PENDING zurückzugeben. STATUS_PENDING ist ein Erfolgscode.

Hinweise

Minifilter sollten FltCheckOplockEx anstelle von FsRtlCheckOplockEx2 aufrufen.

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

Wenn der E/A-Vorgang dazu führt, dass der Oplock unterbrochen wird, wird die Oplockunterbrechung initiiert.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der Oplock-Umbruch abgeschlossen ist und eine Abschlussroutine in CompletionRoutine angegeben wurde, gibt FsRtlCheckOplockEx2 STATUS_PENDING zurück und ruft die in PostIrpRoutine angegebene Rückrufroutine auf. Wenn der Oplock-Umbruch bestätigt wurde, wird die Rückrufroutine in CompletionRoutine aufgerufen.
Wenn der E/A-Vorgang nicht fortgesetzt werden kann, bis der Oplock-Umbruch abgeschlossen und CompletionRoutine nicht angegeben wurde, wird der Thread des Aufrufers blockiert, und FsRtlCheckOplockEx2 wird nur zurückgegeben, wenn der Oplock-Umbruch abgeschlossen ist.

Wenn der Thread des Aufrufers blockiert ist und NotifyRoutine nicht NULL ist, wird NotifyRoutine aus einem oder allen der folgenden in NotifyParams festgelegten Gründe aufgerufen:

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 der Thread des Aufrufers blockiert werden muss, um auf den Abschluss der Unterbrechung zu warten.

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

FsRtlCheckOplockEx2 ignoriert die von NotifyRoutine zurückgegebenen OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT- und OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED status-Codes.

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

Wenn das OPLOCK_FLAG_PARENT_OBJECT-Flag in Flags angegeben ist, unterbricht FsRtlCheckOplockEx2 alle vorhandenen übergeordneten Oplocks bedingungslos. Das heißt, der Hauptcode in der Irp wird nicht berücksichtigt.

Wenn ein Dateisystem oplocks verwendet, muss es FsRtlCheckOplockEx2 aus allen Dispatchroutinen 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: