FsRtlOplockFsctrlEx
TOC
Collapse the table of content
Expand the table of content

FsRtlOplockFsctrlEx routine

The FsRtlOplockFsctrlEx routine performs various opportunistic lock (oplock) operations on behalf of a file system or filter driver.

Syntax


NTSTATUS FsRtlOplockFsctrlEx(
  _In_ POPLOCK Oplock,
  _In_ PIRP    Irp,
  _In_ ULONG   OpenCount,
  _In_ ULONG   Flags
);

Parameters

Oplock [in]

An opaque oplock pointer for the file. This pointer must have been initialized by a previous call to FsRtlInitializeOplock.

Irp [in]

A pointer to the IRP for the I/O operation. This parameter is required and cannot be NULL.

OpenCount [in]

Number of user handles for the file, if an exclusive oplock is being requested. Setting a nonzero value for a level 2, R, or RH oplock request indicates that there are byte-range locks on the file. For information about oplock types, see Oplock Semantics Overview.

Flags [in]

A bitmask for the associated oplock operations. A file system or filter driver sets bits to specify the behavior of FsRtlOplockFsctrlEx. The Flags parameter has the following options:

OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001)

Specifies that the file system verified that all oplock keys on any currently open handles match. By specifying this flag, you allow the oplock package to grant an oplock of level RW or RWH when more than one open handle to the file exists. For more information about oplock types, see the Oplock Semantics Overview page.

Return value

FsRtlOplockFsctrlEx returns one of the following NTSTATUS values:

Return codeDescription
STATUS_SUCCESS

For an IRP_MJ_CREATE request, STATUS_SUCCESS indicates that the requested filter opportunistic lock (oplock) was granted. For a FSCTL operation, the meaning of STATUS_SUCCESS depends on the FSCTL code. For more information, see the reference pages for the FSCTL codes that are listed in the following Remarks section.

STATUS_CANCELLED

The I/O operation was canceled. STATUS_CANCELLED is an error code.

STATUS_INVALID_PARAMETER

The FSCTL code for the I/O operation was not one of the valid values listed in the following Remarks section. STATUS_INVALID_PARAMETER is an error code.

STATUS_OPLOCK_NOT_GRANTED

The oplock could not be granted. STATUS_OPLOCK_NOT_GRANTED is an error code.

STATUS_PENDING

Used only for FSCTL operations. The meaning of STATUS_PENDING depends on the FSCTL code. For more information, see the reference pages for the FSCTL codes that are listed in the following Remarks section. STATUS_PENDING is a success code.

 

Remarks

File systems and filter drivers call FsRtlOplockFsctrlEx to perform various opportunistic lock operations for a create operation or file system control I/O operation. The IRP pointed to by the Irp parameter must be a valid IRP for an IRP_MJ_FILE_SYSTEM_CONTROL or IRP_MJ_CREATE operation.

If the IRP is an IRP_MJ_FILE_SYSTEM_CONTROL request, FsRtlOplockFsctrlEx can be used with the following FSCTL codes. The FSCTL code is set in IrpSp->Parameters.FileSystemControl.FsControlCode. For more information about file system control parameters, see the reference entry for IRP_MJ_FILE_SYSTEM_CONTROL.

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACK_NO_2

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_NOTIFY

FSCTL_REQUEST_BATCH_OPLOCK

FSCTL_REQUEST_FILTER_OPLOCK

FSCTL_REQUEST_OPLOCK_LEVEL_1

FSCTL_REQUEST_OPLOCK_LEVEL_2

FSCTL_REQUEST_OPLOCK

For more information information about these FSCTLs and about opportunistic locks in general, see the Microsoft Windows SDK documentation.

If the IRP is an IRP_MJ_CREATE request, FsRtlOplockFsctrlEx can be used to request a pending filter opportunistic lock (oplock) if all of the following conditions are true:

  • The value of the OpenCount parameter must be 1.

  • The value of the DesiredAccess parameter for the IRP_MJ_CREATE request must be FILE_READ_ATTRIBUTES.

  • The value of the ShareAccess parameter for the IRP_MJ_CREATE request must be FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

If the request for a pending filter oplock is granted, FsRtlOplockFsctrlEx returns STATUS_SUCCESS. For more information about create parameters, see IRP_MJ_CREATE.

Minifilters should call FltOplockFsctrlEx instead of FsRtlOplockFsctrlEx.

Requirements

Target platform

Universal

Version

The FsRtlOplockFsctrlEx routine is available starting with Windows 7.

Header

Ntifs.h (include Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

<= APC_LEVEL

See also

FltOplockFsctrlEx
FSCTL_OPBATCH_ACK_CLOSE_PENDING
FSCTL_OPLOCK_BREAK_ACK_NO_2
FSCTL_OPLOCK_BREAK_ACKNOWLEDGE
FSCTL_OPLOCK_BREAK_NOTIFY
FSCTL_REQUEST_BATCH_OPLOCK
FSCTL_REQUEST_FILTER_OPLOCK
FSCTL_REQUEST_OPLOCK
FSCTL_REQUEST_OPLOCK_LEVEL_1
FSCTL_REQUEST_OPLOCK_LEVEL_2
FsRtlInitializeOplock
IRP_MJ_CREATE
IRP_MJ_FILE_SYSTEM_CONTROL

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft