FltCheckOplockEx function (fltkernel.h)

A minifilter driver calls the FltCheckOplockEx routine to synchronize the callback data structure for an IRP-based file I/O operation that has the current opportunistic lock (oplock) state of the file.

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Parameters

[in] Oplock

An opaque oplock pointer for the file. This pointer must have been initialized by a previous call to FltInitializeOplock.

[in] CallbackData

A pointer to the callback data FLT_CALLBACK_DATAstructure for the I/O operation.

[in] Flags

A bitmask for the associated file I/O operation. A minifilter driver sets bits to specify the behavior of FltCheckOplockEx. The Flags parameter has the following options:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Allows an opportunistic lock break to proceed without blocking or pending the operation that caused the oplock break.

OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)

Specifies that FltCheckOplockEx should only check for an opportunistic lock key on the FILE_OBJECT that is associated with the I/O operation. This I/O operations is represented by the callback data that the CallbackData parameter points to. FltCheckOplockEx must then add the key if one is provided in the I/O operation. No other oplock processing occurs; that is, no opportunistic lock break will occur.

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

Specifies that FsRtlCheckOplockEx should revert any state that was previously set up through a call to the FltOplockFsctrl routine. FltOplockFsctrl is called when an IRP_MJ_CREATE request is processed. This IRP_MJ_CREATE request specifies the FILE_OPEN_REQUIRING_OPLOCK flag in the create options parameter. The OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK flag is typically used in final processing of such a create request when it previously failed.

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Allows all opportunistic lock breaks to proceed regardless of the opportunistic lock key.

[in, optional] Context

A pointer to caller-defined context information to be passed to the callback routines that WaitCompletionRoutine and PrePostCallbackDataRoutine point to. The Filter Manager treats this information as opaque.

[in, optional] WaitCompletionRoutine

A pointer to a caller-supplied callback routine. If an oplock break is in progress, the Filter Manager calls this routine when the oplock break is completed. This parameter is optional and can be NULL. If it is NULL, the caller is put into a wait state until the oplock break is completed.

This routine is declared as follows:

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

This routine has the following parameters:

CallbackData

A pointer to the callback data structure for the I/O operation.

Note that when your WaitCompleteRoutine is called, the IoStatus sub-structure might be filled in with a failure status (for instance STATUS_CANCELLED). You should inspect this status and react appropriately.

Context

A context information pointer that was passed in the Context parameter to FltCheckOplockEx.

[in, optional] PrePostCallbackDataRoutine

A pointer to a caller-supplied callback routine to be called if the I/O operation is posted to a work queue. This parameter is optional and can be NULL.

This routine is declared as follows:

typedef VOID
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

CallbackData

A pointer to the callback data structure for the I/O operation.

Context

A context information pointer that was passed in the Context parameter to FltCheckOplockEx.

Return value

FltCheckOplockEx returns one of the following FLT_PREOP_CALLBACK_STATUS codes:

Remarks

A minifilter driver calls FltCheckOplockEx to synchronize an IRP-based I/O operation with the current oplock state of a file according to the following conditions:

• If the I/O operation will cause the oplock to break, the oplock break is initiated.

• If the I/O operation cannot continue until the oplock break is complete, FltCheckOplockEx returns FLT_PREOP_PENDING and calls the callback routine that the PrePostCallbackDataRoutine parameter points to.

• If a minifilter driver uses oplocks, it must call FltCheckOplockEx from any preoperation callback (PFLT_PRE_OPERATION_CALLBACK) routine for I/O operations that can cause oplock breaks. This rule applies to the following types of I/O operations, because these operations can cause oplock breaks:

  • IRP_MJ_CLEANUP

  • IRP_MJ_CREATE

  • IRP_MJ_FILE_SYSTEM_CONTROL

  • IRP_MJ_FLUSH_BUFFERS

  • IRP_MJ_LOCK_CONTROL

  • IRP_MJ_READ

  • IRP_MJ_SET_INFORMATION

  • IRP_MJ_WRITE

The I/O operation must be an IRP-based I/O operation. To determine whether a given callback data structure represents an IRP-based I/O operation, use the FLT_IS_IRP_OPERATION macro.

Minifilters must not call FltCheckOplockEx again within the callback specified in WaitCompletionRoutine. Doing so can result in a deadlock condition if the oplock package calls the completion callback before FltCheckOplockEx returns.

For more information about opportunistic locks, see the Microsoft Windows SDK documentation.

Requirements

See also

FLT_CALLBACK_DATA

FLT_IS_IRP_OPERATION

FltInitializeOplock

FltOplockFsctrl

FsRtlCheckOplockEx

IO_STATUS_BLOCK

PFLT_PRE_OPERATION_CALLBACK