FltOplockFsctrlEx function (fltkernel.h)

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

Syntax

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

Parameters

[in] Oplock

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

[in] CallbackData

Pointer to the FLT_CALLBACK_DATA structure for the I/O operation. This parameter is required and cannot be NULL.

[in] OpenCount

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 Overview.

[in] 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:

Value Meaning
OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001) 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 Oplock Overview.

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, FltOplockFsctrlEx can be used with the following FSCTL codes:

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, FltOplockFsctrl can be used to request a pending filter opportunistic lock 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 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.

Filters and file systems that call this function must synchronize calls into the system-supplied oplock package. See Oplock synchronization for more information.

Requirements

Requirement Value
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

FltCheckOplockEx

FltInitializeOplock

FsRtlOplockFsctrlEx

IRP_MJ_CREATE

IRP_MJ_FILE_SYSTEM_CONTROL