FSCTL_REQUEST_OPLOCK control code

Requests an opportunistic lock (oplock) on a file and acknowledges that an oplock break has occurred.

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


BOOL DeviceIoControl( (HANDLE) hDevice,              // handle to file
                     FSCTL_REQUEST_OPLOCK,          // dwIoControlCode
                     (LPVOID) lpInBuffer,           // input buffer
                     (DWORD) nInBufferSize,         // size of input buffer
                     (LPVOID) lpOutBuffer,          // output buffer
                     (DWORD) nOutBufferSize,        // size of output buffer
                     (LPDWORD) lpBytesReturned,     // number of bytes returned
                     (LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure

Parameters

hDevice

A handle to the file or alternate stream for which the opportunistic lock is requested. To retrieve a handle, call the CreateFile function. The file or alternate stream must have been opened with the flag FILE_FLAG_OVERLAPPED.

dwIoControlCode

The control code for the operation. Use FSCTL_REQUEST_OPLOCK for this operation.

lpInBuffer

A pointer to a buffer that contains a REQUEST_OPLOCK_INPUT_BUFFER structure.

nInBufferSize

The size of the input buffer, in bytes.

lpOutBuffer

A pointer to a buffer that receives a REQUEST_OPLOCK_OUTPUT_BUFFER structure.

nOutBufferSize

The size of the output buffer, in bytes.

lpBytesReturned

A pointer to a variable that receives the size of the data stored in the output buffer, in bytes.

This parameter is meaningless until the overlapped operation has completed. To retrieve the number of bytes returned, call GetOverlappedResult. If hDevice is associated with an I/O completion port, you can retrieve the number of bytes returned by calling GetQueuedCompletionStatus.

lpOverlapped

A pointer to an OVERLAPPED structure.

Because hDevice was opened with the FILE_FLAG_OVERLAPPED flag, the operation is performed as an overlapped (asynchronous) operation. Therefore, lpOverlapped must point to a valid OVERLAPPED structure that contains a handle to an event object. Otherwise, the function fails in unpredictable ways.

DeviceIoControl returns immediately, and the event object is signaled when the operation has been completed.

Return value

If the operation completes successfully, DeviceIoControl returns a nonzero value. To determine if the opportunistic lock is granted, call GetLastError. The code ERROR_IO_PENDING indicates that the opportunistic lock was granted. Any other code indicates that the request was denied.

If the operation fails or is pending, DeviceIoControl returns zero. To get extended error information, call GetLastError.

Remarks

This operation is used only by client applications requesting an opportunistic lock (oplock) 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.

The FSCTL_REQUEST_OPLOCK control code provides more efficient functionality than the following related control codes: FSCTL_REQUEST_OPLOCK_LEVEL_1, FSCTL_REQUEST_OPLOCK_LEVEL_2, FSCTL_REQUEST_FILTER_OPLOCK, and FSCTL_REQUEST_BATCH_OPLOCK. Requesting different oplock levels can be performed repeatedly on the same handle without closing and reopening the handle when using FSCTL_REQUEST_OPLOCK; the other control codes require that the handle be closed and then reopened with CreateFile to make such a change. This is accomplished by manipulating the RequestedOplockLevel member of the REQUEST_OPLOCK_INPUT_BUFFER structure when re-issuing the FSCTL_REQUEST_OPLOCK control code.

The following table summarizes how the caching ability of oplock types available from FSCTL_REQUEST_OPLOCK correspond to the level 2, level 1, and batch oplocks.

Alternative control codeEquivalent RequestedOplockLevel flags valueOplock type
FSCTL_REQUEST_BATCH_OPLOCK OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_WRITE | OPLOCK_LEVEL_CACHE_HANDLERWH
FSCTL_REQUEST_OPLOCK_LEVEL_1 OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_WRITE RW
FSCTL_REQUEST_OPLOCK_LEVEL_2 OPLOCK_LEVEL_CACHE_READR

 

Using the FSCTL_REQUEST_OPLOCK control code with the RequestedOplockLevel member set to OPLOCK_LEVEL_CACHE_READ | OPLOCK_LEVEL_CACHE_HANDLE grants an oplock of type RH. An RH oplock is similar to the filter oplock granted by the FSCTL_REQUEST_FILTER_OPLOCK control code. However, note that the filter oplock allows only one client to hold an oplock on a file at a time; FSCTL_REQUEST_OPLOCK allows multiple clients at a time to have the RH lock on a file. Another difference is that FSCTL_REQUEST_FILTER_OPLOCK requires an oplock break acknowledgment before writes can occur, where FSCTL_REQUEST_OPLOCK does not because the oplock break notification is advisory-only and writes are allowed to go ahead without acknowledgment. For more information, see Breaking Oplocks.

An FSCTL_REQUEST_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.

TechnologySupported

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 7 [desktop apps only]

Minimum supported server

Windows Server 2008 R2 [desktop apps only]

Header

WinIoCtl.h (include Windows.h)

See also

Oplock Semantics
CreateFile
DeviceIoControl
Opportunistic Locks
OVERLAPPED

 

 

Community Additions

ADD
Show:
© 2014 Microsoft