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:
- 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, 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_PARAMETERS for IRP_MJ_CREATE
FLT_PARAMETERS for IRP_MJ_FILE_SYSTEM_CONTROL
FSCTL_OPBATCH_ACK_CLOSE_PENDING