FSCTL_REQUEST_OPLOCK_LEVEL_2 control code

Applies to: desktop apps only

Requests a level 2 opportunistic lock on a file.

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

BOOL DeviceIoControl( (HANDLE) hDevice,              // handle to file
                      FSCTL_REQUEST_OPLOCK_LEVEL_2,  // dwIoControlCode
                      NULL,                          // lpInBuffer
                      0,                             // nInBufferSize
                      NULL,                          // lpOutBuffer
                      0,                             // nOutBufferSize
                      (LPDWORD) lpBytesReturned,     // number of bytes returned
                      (LPOVERLAPPED) lpOverlapped ); // OVERLAPPED structure

Parameters

hDevice

A handle to the file or alternate stream on 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_LEVEL_2 for this operation.

lpInBuffer

Not used with this operation; set to NULL.

nInBufferSize

Not used with this operation; set to zero.

lpOutBuffer

Not used with this operation; set to NULL.

nOutBufferSize

Not used with this operation; set to zero.

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 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_OPLOCK_LEVEL_2 to request a level 2 opportunistic lock on a file. A client file system can cache read data (but not write data) locally as long as the level 2 lock is held.

The file system requires no acknowledgment from the application that requested the level 2 opportunistic lock when the lock is broken. 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 Breaking Oplocks.

For more information, see Types of Opportunistic Locks.

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

An FSCTL_REQUEST_OPLOCK_LEVEL_2 control code fails if the file is opened in nonoverlapped (synchronous) mode.

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

Requirements

See also

Oplock Semantics

CreateFile

DeviceIoControl

FSCTL_REQUEST_OPLOCK

Opportunistic Locks

OVERLAPPED

Send comments about this topic to Microsoft

Build date: 4/17/2012