FsRtlCheckOplock-Funktion (ntifs.h)

Artikel
02/29/2024

Die FsRtlCheckOplock-Routine synchronisiert den IRP für einen Datei-E/A-Vorgang mit dem aktuellen oplock-Zustand (Opportunistic Lock) 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 FsRtlInitializeOplock initialisiert worden sein.

[in] Irp

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

[in, optional] Context

Ein Zeiger auf vom Aufrufer definierte Kontextinformationen, die an die Rückrufroutine übergeben werden sollen, auf die die CompletionRoutine - und PostIrpRoutine-Parameter verweisen.

[in, optional] CompletionRoutine

Ein Zeiger auf eine vom Anrufer 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 es NULL ist, wird der Aufrufer in einen Wartezustand versetzt, bis die opportunistische Sperrunterbrechung 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
Kontext	Ein Kontextinformationszeiger, der im Context-Parameter an FsRtlCheckOplock ü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 hat die folgenden Parameter:

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

Rückgabewert

Die FsRtlCheckOplock-Routine 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	Wenn das IRP ein IRP_MJ_CREATE ist und FILE_OPEN_REQUIRING_OPLOCK sich in den CreateOptions des IRP befindet, löst die Routine keinen Bruch einer vorhandenen opportunistischen Sperre aus, schlägt aber mit STATUS_CANNOT_BREAK_OPLOCK fehl.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Ein opportunistischer Sperrbruch ist im Gange. Die IRP ist eine IRP_MJ_CREATE Anforderung, und FILE_COMPLETE_IF_OPLOCKED im Parameter create options für den Vorgang angegeben wurde. STATUS_OPLOCK_BREAK_IN_PROGRESS ist ein Erfolgscode.
STATUS_PENDING	Es wurde eine opportunistische Sperrunterbrechung 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

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

Wenn der E/A-Vorgang dazu führt, 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, gibt FsRtlCheckOplock STATUS_PENDING zurück und ruft die Rückrufroutine-Routine auf, auf die der PostIrpRoutine-Parameter verweist.

Wenn ein Dateisystem oder Filtertreiber opportunistische Sperren verwendet, muss fsRtlCheckOplock von allen Dispatchroutinen für E/A-Vorgänge aufgerufen werden, 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 FsRtlCheckOplock aufrufen.

Anforderungen

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