Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
FsRtlOplockFsctrl performs various opportunistic lock (oplock) operations on behalf of a file system or filter driver.
Syntax
NTSTATUS FsRtlOplockFsctrl(
[in] POPLOCK Oplock,
[in] PIRP Irp,
[in] ULONG OpenCount
);
Parameters
[in] Oplock
Opaque oplock pointer for the file. This pointer must have been initialized by a previous call to FsRtlInitializeOplock.
[in] Irp
Pointer to the IRP 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.
Return value
FsRtlOplockFsctrl returns one of the following NTSTATUS values:
| Return code | Description |
|---|---|
| STATUS_SUCCESS | For an IRP_MJ_CREATE request, STATUS_SUCCESS indicates that the requested filter 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 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 listed in the following Remarks section. STATUS_PENDING is a success code. |
| STATUS_CANNOT_BREAK_OPLOCK | A new oplock could not be granted. The IRP is an IRP_MJ_CREATE request and FILE_OPEN_REQUIRING_OPLOCK was specified in the create options parameter for the operation. STATUS_CANNOT_BREAK_OPLOCK is a success code. |
Remarks
File systems and legacy filter drivers call FsRtlOplockFsctrl to perform various oplock operations for a create or file system control I/O operation. Minifilters should call FltOplockFsctrl instead of FsRtlOplockFsctrl.
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, FsRtlOplockFsctrl can be used with one of the following FSCTL codes, which is set in IrpSp->Parameters.FileSystemControl.FsControlCode:
- 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
For detailed 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, FsRtlOplockFsctrl can be used to request a pending filter 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, FsRtlOplockFsctrl returns STATUS_SUCCESS. For more information about create parameters, see the reference entry 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 |
|---|---|
| Target Platform | Universal |
| Header | ntifs.h (include Ntifs.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= APC_LEVEL |
See also
FSCTL_OPBATCH_ACK_CLOSE_PENDING