FsRtlCheckUpperOplock function (ntifs.h)
The FsRtlCheckUpperOplock routine provides opportunistic lock (oplock) checking in secondary, or layered, file systems when the oplocks they hold change state. Secondary file systems, such as network redirectors and clustering file services, call FsRtlCheckUpperOplock when an oplock held in a lower file system by the secondary file system, changes state. A state change can occur either by a break or an upgrade. FsRtlCheckUpperOplock will break the oplock of upper file system, if necessary, to confirm the new lower oplock state. The caller can also provide optional callbacks for notifications of break acknowledgment and pending status.
Syntax
NTSTATUS FsRtlCheckUpperOplock(
[in] POPLOCK Oplock,
[in] ULONG NewLowerOplockState,
[in, optional] PVOID CompletionRoutineContext,
[in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
POPLOCK_FS_PREPOST_IRP PrePendRoutine,
[in] ULONG Flags
);
Parameters
[in] Oplock
An opaque oplock pointer for the file. This pointer must have been initialized by a previous call to FsRtlInitializeOplock.
[in] NewLowerOplockState
A value representing the requested oplock held in a lower file system by a secondary file system. This a bitwise OR combination of the following:
| Value | Meaning |
|---|---|
| OPLOCK_LEVEL_CACHE_READ | Indicates an oplock Read (R) type. |
| OPLOCK_LEVEL_CACHE_WRITE | Indicates an oplock Write (W) type. |
| OPLOCK_LEVEL_CACHE_HANDLE | Indicates an oplock Handle (H) type. |
[in, optional] CompletionRoutineContext
A pointer to caller-defined context information to be passed to the callback routines that the CompletionRoutine and PrePendIrpRoutine parameters point to.
[in, optional] CompletionRoutine
A pointer to a caller-supplied callback routine. If an opportunistic lock break is in progress, this routine is called when the break is completed. This parameter is optional and can be NULL. If it is NULL, the caller is put into a wait state until the opportunistic lock break is completed.
This routine's declaration and parameter descriptions are as follows:
typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
_In_ PVOID Context,
_In_opt_ PIRP Irp
);
| Parameter | Description |
|---|---|
| Context | A context information pointer that was passed in the CompletionRoutineContext parameter to FsRtlCheckUpperOplock. |
| Irp | An optional pointer to the IRP for the I/O operation. FsRtlCheckUpperOplock will always set this to NULL. |
PrePendRoutine
A pointer to a caller-supplied callback routine to be called if FsRtlCheckUpperOplock will return STATUS_PENDING. This parameter is optional and can be NULL.
This routine's declaration and parameter descriptions are as follows:
typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
_In_ PVOID Context,
_in_opt_ PIRP Irp
);
| Parameter | Description |
|---|---|
| Context | A context information pointer that was passed in the CompletionRoutineContext parameter to FsRtlCheckUpperOplock. |
| Irp | An optional pointer to the IRP for the I/O operation. FsRtlCheckUpperOplock will always set this to NULL. |
[in] Flags
A bitmask for the associated file I/O operation. A file system or filter driver sets bits to specify the behavior of FsRtlCheckUpperOplock. The Flags parameter has the following options:
| Value | Meaning |
|---|---|
| OPLOCK_UPPER_FLAG_CHECK_NO_BREAK (0x00010000) | Return STATUS_CANNOT_BREAK_OPLOCK if the value of NewLowerOplockState results in any oplock break. |
| OPLOCK_UPPER_FLAG_NOTIFY_REFRESH_READ (0x00020000) | Break only Read (R) upper oplocks and notify R holders that they may again request R. All other upper oplock checks it will return STATUS_CANNOT_BREAK_OPLOCK. |
Return value
FsRtlCheckUpperOplock returns an appropriate NTSTATUS code such as one of the following:
| Return code | Description |
|---|---|
| STATUS_SUCCESS | An oplock break is not required or the break was acknowledged. If CompletionRoutine is NULL, FsRtlCheckUpperOplock blocks while the oplock break is processed rather than return STATUS_PENDING. |
| STATUS_CANNOT_BREAK_OPLOCK | The oplock break cannot be accomplished. See Flags for conditions that restrict a break. |
| STATUS_PENDING | An opportunistic lock break is underway. If supplied, PrePendIrpRoutine is called as a notification of the pending operation. CompletionRoutine is called when the oplock break is complete. STATUS_PENDING is a success code. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1 |
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |