FsRtlOplockFsctrl-Funktion (ntifs.h)

Artikel
02/26/2024

FsRtlOplockFsctrl führt verschiedene oplock-Vorgänge (Opportunistic Lock) im Namen eines Dateisystems oder Filtertreibers aus.

Syntax

NTSTATUS FsRtlOplockFsctrl(
  [in] POPLOCK Oplock,
  [in] PIRP    Irp,
  [in] ULONG   OpenCount
);

Parameter

[in] Oplock

Undurchsichtiger Oplockzeiger für die Datei. Dieser Zeiger muss durch einen vorherigen Aufruf von FsRtlInitializeOplock initialisiert worden sein.

[in] Irp

Zeiger auf den IRP für den E/A-Vorgang. Dieser Parameter ist erforderlich und darf nicht NULL sein.

[in] OpenCount

Anzahl der Benutzerhandles für die Datei, wenn ein exklusiver Oplock angefordert wird. Das Festlegen eines Werts ungleich null für eine Oplockanforderung der Ebene 2, R oder RH gibt an, dass für die Datei Bytebereichssperren vorhanden sind. Informationen zu Oplock-Typen finden Sie unter Übersicht über Oplock.

Rückgabewert

FsRtlOplockFsctrl gibt einen der folgenden NTSTATUS-Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Bei einer IRP_MJ_CREATE-Anforderung gibt STATUS_SUCCESS an, dass der angeforderte Filter-Oplock gewährt wurde. Bei einem FSCTL-Vorgang hängt die Bedeutung von STATUS_SUCCESS vom FSCTL-Code ab. Weitere Informationen finden Sie auf den Referenzseiten für die FSCTL-Codes, die im folgenden Abschnitt "Hinweise" aufgeführt sind.
STATUS_CANCELLED	Der E/A-Vorgang wurde abgebrochen. STATUS_CANCELLED ist ein Fehlercode.
STATUS_INVALID_PARAMETER	Der FSCTL-Code für den E/A-Vorgang war keiner der im folgenden Abschnitt "Hinweise" aufgeführten gültigen Werte. STATUS_INVALID_PARAMETER ist ein Fehlercode.
STATUS_OPLOCK_NOT_GRANTED	Der Oplock konnte nicht gewährt werden. STATUS_OPLOCK_NOT_GRANTED ist ein Fehlercode.
STATUS_PENDING	Wird nur für FSCTL-Vorgänge verwendet. Die Bedeutung von STATUS_PENDING hängt vom FSCTL-Code ab. Weitere Informationen finden Sie auf den Referenzseiten für die FSCTL-Codes, die im folgenden Abschnitt "Hinweise" aufgeführt sind. STATUS_PENDING ist ein Erfolgscode.
STATUS_CANNOT_BREAK_OPLOCK	Ein neuer Oplock konnte nicht gewährt werden. Das IRP ist eine IRP_MJ_CREATE-Anforderung, und FILE_OPEN_REQUIRING_OPLOCK im Parameter create options für den Vorgang angegeben wurde. STATUS_CANNOT_BREAK_OPLOCK ist ein Erfolgscode.

Hinweise

Dateisysteme und Ältere Filtertreiber rufen FsRtlOplockFsctrl auf, um verschiedene Oplock-Vorgänge für einen E/A-Vorgang der Erstellungs- oder Dateisystemsteuerung auszuführen. Minifilter sollten FltOplockFsctrl anstelle von FsRtlOplockFsctrl aufrufen.

Das IRP, auf das der Irp-Parameter verweist, muss ein gültiger IRP für einen IRP_MJ_FILE_SYSTEM_CONTROL- oder IRP_MJ_CREATE-Vorgang sein.

Wenn das IRP eine IRP_MJ_FILE_SYSTEM_CONTROL-Anforderung ist, kann FsRtlOplockFsctrl mit einem der folgenden FSCTL-Codes verwendet werden, der in IrpSp-Parameters.FileSystemControl.FsControlCode> festgelegt ist:

Ausführliche Informationen zu diesen FSCTLs und zu opportunistischen Sperren im Allgemeinen finden Sie in der Dokumentation zu Microsoft Windows SDK.

Wenn das IRP eine IRP_MJ_CREATE-Anforderung ist, kann FsRtlOplockFsctrl verwendet werden, um einen ausstehenden Filter-Oplock anzufordern, wenn alle der folgenden Bedingungen erfüllt sind:

Der Wert des OpenCount-Parameters muss 1 sein.
Der Wert des DesiredAccess-Parameters für die IRP_MJ_CREATE-Anforderung muss FILE_READ_ATTRIBUTES sein.
Der Wert des ShareAccess-Parameters für die IRP_MJ_CREATE-Anforderung muss FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Wenn der Anforderung für einen ausstehenden Filter oplock erteilt wird, gibt FsRtlOplockFsctrl STATUS_SUCCESS zurück. Weitere Informationen zu Erstellungsparametern finden Sie im Referenzeintrag für IRP_MJ_CREATE.

Filter und Dateisysteme, die diese Funktion aufrufen, müssen Aufrufe mit dem vom System bereitgestellten oplock-Paket synchronisieren. Weitere Informationen finden Sie unter Oplock-Synchronisierung .