FSCTL_REQUEST_FILTER_OPLOCK IOCTL

Requests a filter opportunistic lock on a file.

To perform this operation, call the DeviceIoControl function using the following parameters.

C++
BOOL DeviceIoControl( (HANDLE) hDevice,              // handle to file
                      FSCTL_REQUEST_FILTER_OPLOCK,   // dwIoControlCodeNULL,                          // lpInBuffer0,                             // nInBufferSizeNULL,                          // lpOutBuffer0,                             // nOutBufferSize(LPDWORD) lpBytesReturned,     // number of bytes returned
                      (LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure

Major Code

IRP_MJ_DEVICE_CONTROL

Input Buffer

Input Buffer Length

Output Buffer

Output Buffer Length

Input / Output Buffer

Input / Output Buffer Length

Status Block

Irp->IoStatus.Status is set to STATUS_SUCCESS if the request is successful.

Otherwise, Status to the appropriate error condition as a NTSTATUS code.

For more information, see NTSTATUS Values.

Remarks

This operation is used only by client applications requesting an opportunistic lock from a local server. Client applications requesting opportunistic locks from remote servers must not request them directly—the network redirector transparently requests opportunistic locks for the application. An attempt to use this operation to request opportunistic locks from remote servers will result in the request being denied.

If a new oplock type is desired, the handle must be closed and a new handle reopened using CreateFile, and DeviceIoControl must be called on the new handle with the desired FSCTL_REQUEST_OPLOCK_XXX control code. To request an oplock on a handle that can have the oplock type changed in place (the handle does not have to be closed and reopened), use the FSCTL_REQUEST_OPLOCK control code.

Use FSCTL_REQUEST_FILTER_OPLOCK to request a filter opportunistic lock on a file. A client file system can cache read data and handle data locally as long as the filter lock is held, but only one client can hold the lock at a time.

The filter oplock owner must acknowledge an oplock break (see Breaking opportunistic locks) before any operation that is incompatible with a filter oplock can go through on another handle. After the lock is broken, the network redirector is notified not to regard as valid any cached data from the file.

For more information, see Types of Opportunistic Locks.

For a comparison of the various oplock control codes, see FSCTL_REQUEST_OPLOCK.

An FSCTL_REQUEST_FILTER_OPLOCK control code fails if the file is opened in non-overlapped (synchronous) mode.

For the implications of overlapped I/O on this operation, see the Remarks section of the DeviceIoControl topic.

In Windows 8 and Windows Server 2012, this code is supported by the following technologies.

Technology Supported
Server Message Block (SMB) 3.0 protocol No
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 with Scale-out File Shares (SO) No
Cluster Shared Volume File System (CsvFS) Yes
Resilient File System (ReFS) Yes

Requirements

   
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Header winioctl.h (include Windows.h)

See Also

CreateFile

DeviceIoControl

FSCTL_REQUEST_OPLOCK

OVERLAPPED

Oplock Semantics

Opportunistic Locks