FsRtlOplockFsctrl-Funktion (ntifs.h)

Artikel
12/20/2024

FsRtlOplockFsctrl führt verschiedene opportunistische Sperrvorgänge (Oplock) im Auftrag eines Dateisystems oder Filtertreibers aus.

Syntax

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

Parameter

[in] Oplock

Opaque oplock pointer for the file. Dieser Zeiger muss durch einen vorherigen Aufruf von fsRtlInitializeOplockinitialisiert worden sein.

[in] Irp

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

[in] OpenCount

Anzahl der Benutzerhandles für die Datei, wenn ein exklusiver Oplock angefordert wird. Wenn Sie einen Wert ungleich Null für eine Oplockanforderung der Ebene 2, R oder RH festlegen, wird angegeben, dass die Datei über Bytebereichssperren verfügt. Informationen zu Oplock-Typen finden Sie unter Oplock Overview.

Rückgabewert

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

Rückgabecode	Beschreibung
STATUS_SUCCESS	Für eine 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 gültigen Werte, die im folgenden Abschnitt "Hinweise" aufgeführt sind. 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 zum Erstellen von Optionen für den Vorgang angegeben wurde. STATUS_CANNOT_BREAK_OPLOCK ist ein Erfolgscode.

Bemerkungen

Dateisysteme und Ältere Filtertreiber rufen FsRtlOplockFsctrl auf, um verschiedene Oplock-Vorgänge für einen Vorgang zur Erstellung oder Dateisystemsteuerung auszuführen. Minifilter sollten FltOplockFsctrl anstelle von FsRtlOplockFsctrlaufrufen.

Das IRP, auf das der Irp--Parameter verweist, muss ein gültiges 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, können FsRtlOplockFsctrl mit einem der folgenden FSCTL-Codes verwendet werden, die in IrpSp->Parameters.FileSystemControl.FsControlCodefestgelegt wird:

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

Wenn das IRP eine IRP_MJ_CREATE Anforderung ist, können FsRtlOplockFsctrl verwendet werden, um einen ausstehenden Filter-Oplock anzufordern, wenn alle 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 die Anforderung für einen ausstehenden Filter oplock gewährt wird, gibt FsRtlOplockFsctrl STATUS_SUCCESS zurück. Weitere Informationen zum Erstellen von Parametern finden Sie im Referenzeintrag für IRP_MJ_CREATE.

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