FsRtlOplockFsctrlEx-Funktion (ntifs.h)

Artikel
2024-12-20

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

Syntax

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

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.

[in] Flags

Eine Bitmaske für die zugeordneten Oplock-Vorgänge. Ein Dateisystem oder Filtertreiber legt Bits fest, um das Verhalten von FsRtlOplockFsctrlExanzugeben. Dieser Parameter hat die folgenden Optionen:

Flagge	Bedeutung
OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001)	Das Dateisystem hat überprüft, ob alle Oplock-Schlüssel auf allen aktuell geöffneten Handles übereinstimmen. Wenn Sie dieses Kennzeichen angeben, können Sie dem Oplock-Paket ein Oplock der Ebene RW oder RWH gewähren, wenn mehr als ein geöffnetes Handle für die Datei vorhanden ist. Weitere Informationen zu Oplock-Typen finden Sie unter Oplock Overview.

Rückgabewert

FsRtlOplockFsctrlEx 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 FsRtlOplockFsctrlEx- auf, um verschiedene Oplock-Vorgänge für einen E/A-Vorgang für die Erstellung oder Dateisystemsteuerung auszuführen. Minifilter sollten FltOplockFsctrlEx- anstelle von FsRtlOplockFsctrlExaufrufen.

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 FsRtlOplockFsctrlEx- mit einem der folgenden FSCTL-Codes verwendet werden, die in IrpSp->Parameters.FileSystemControl.FsControlCodefestgelegt wird:

Weitere 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 FsRtlOplockFsctrlEx- 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 FsRtlOplockFsctrlEx 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-.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Die FsRtlOplockFsctrlEx-Routine ist ab Windows 7 verfügbar.
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	<= APC_LEVEL