FltOplockFsctrlEx function

The FltOplockFsctrlEx routine performs various opportunistic lock (oplock) operations on behalf of a minifilter driver.

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltOplockFsctrlEx(
  POPLOCK            Oplock,
  PFLT_CALLBACK_DATA CallbackData,
  ULONG              OpenCount,
  ULONG              Flags
);

Parameters

Oplock

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

CallbackData

A pointer to the callback data structure for the I/O operation (FLT_CALLBACK_DATA). This parameter is required and cannot be NULL.

OpenCount

The 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

A bitmask for the associated oplock operations. A minifilter driver sets bits to specify the behavior of FltOplockFsctrlEx. 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 handles that are currently open 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

FltOplockFsctrlEx returns FLT_PREOP_PENDING for some FSCTL operations. For more information, see the reference pages for the FSCTL codes listed in the following Remarks section. Otherwise, FltOplockFsctrlEx returns FLT_PREOP_COMPLETE.

Remarks

A minifilter driver calls FltOplockFsctrlEx to perform various opportunistic lock operations for a create operation or file system control I/O operation. The FLT_CALLBACK_DATA structure pointed to by the CallbackData parameter must represent an IRP-based IRP_MJ_FILE_SYSTEM_CONTROL or IRP_MJ_CREATE operation.

If the operation is an IRP_MJ_FILE_SYSTEM_CONTROL operation, you can use FltOplockFsctrlEx with the following FSCTL codes:

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

The FSCTL code is set in the FsControlCode member of the FLT_PARAMETERS structure for the operation. For more information about FsControlCode and other IRP_MJ_FILE_SYSTEM_CONTROL parameters, see FLT_PARAMETERS for IRP_MJ_FILE_SYSTEM_CONTROL.

For more information about opportunistic locks, see the Microsoft Windows SDK documentation.

If the operation is an IRP_MJ_CREATE request, you can use FltOplockFsctrlEx to request a pending filter opportunistic lock if all of the following conditions are true:

  • The value of the OpenCount parameter is 1.
  • The value of the DesiredAccess parameter for the IRP_MJ_CREATE request is FILE_READ_ATTRIBUTES. This parameter is set in the SecurityContext member of the FLT_PARAMETERS structure for the operation. For more information, see FLT_PARAMETERS for IRP_MJ_CREATE.
  • The value of the ShareAccess parameter for the IRP_MJ_CREATE operation is FILE_SHARE_READ, FILE_SHARE_WRITE, or FILE_SHARE_DELETE. This parameter is set in the ShareAccess member of the FLT_PARAMETERS structure for the operation. For more information, see FLT_PARAMETERS for IRP_MJ_CREATE.

Requirements

   
Minimum supported client This routine is available starting with Windows 8.
Target Platform Universal
Header fltkernel.h (include Fltkernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL "<= APC_LEVEL"

See Also

FLT_CALLBACK_DATA

FLT_PARAMETERS for IRP_MJ_CREATE

FLT_PARAMETERS for IRP_MJ_FILE_SYSTEM_CONTROL

FSCTL_OPBATCH_ACK_CLOSE_PENDING

FSCTL_OPLOCK_BREAK_ACKNOWLEDGE

FSCTL_OPLOCK_BREAK_ACK_NO_2

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

FltInitializeOplock

FsRtlOplockFsctrlEx

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL