FsRtlCheckOplock-Funktion (ntifs.h)

Artikel
12/21/2024

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

Syntax

NTSTATUS FsRtlCheckOplock(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [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, 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 FsRtlCheckOplockü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 FsRtlCheckOplockübergeben wurde.
Irp	Ein Zeiger auf das IRP für den E/A-Vorgang.

Rückgabewert

Die FsRtlCheckOplock Routine 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	Wenn das IRP ein IRP_MJ_CREATE ist und FILE_OPEN_REQUIRING_OPLOCK sich in den CreateOptions des IRP befindet, initiiert die Routine keine Unterbrechung einer vorhandenen opportunistischen Sperre, schlägt jedoch mit STATUS_CANNOT_BREAK_OPLOCK fehl.
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.
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

FsRtlCheckOplock 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, gibt FsRtlCheckOplock STATUS_PENDING zurück und ruft die Rückrufroutine auf, auf die der PostIrpRoutine Parameter verweist.

Wenn ein Dateisystem oder Filtertreiber opportunistische Sperren verwendet, muss er FsRtlCheckOplock 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

Ausführliche Informationen zu opportunistischen Sperren finden Sie in der Windows SDK-Dokumentation.

Minifilter sollten FltCheckOplock- anstelle von FsRtlCheckOplockaufrufen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000
Zielplattform-	Universal
Header-	ntifs.h (include FltKernel.h, Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	<= APC_LEVEL