Edit

FltOplockBreakH function (fltkernel.h)

  • Article

The FltOplockBreakH routine breaks CACHE_HANDLE_LEVEL opportunistic locks (oplocks).

Syntax

FLT_PREOP_CALLBACK_STATUS FLTAPI FltOplockBreakH(
  [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_DATA) structure 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 FltOplockBreakH. The Flags parameter has the following options:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

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

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Allows CACHE_HANDLE_LEVEL oplock breaks to proceed regardless of the oplock key.

[in, optional] Context

A pointer to caller-defined context information to be passed to the callback routines that the WaitCompletionRoutine and PrePostCallbackDataRoutine parameters point to.

[in, optional] WaitCompletionRoutine

A pointer to a caller-supplied callback routine. If an oplock break is in progress, this routine is called when the 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_opt PVOID Context
    );

This routine has the following parameters:

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 FltOplockBreakH.

[in, optional] PrePostCallbackDataRoutine

A pointer to a caller-supplied callback routine to be called if the I/O operation must be pended. The routine is called before the oplock package pends the IRP. 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_opt PVOID Context
      );

This routine has the following parameters:

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 FltOplockBreakH.

Return value

FltOplockBreakH returns one of the following FLT_PREOP_CALLBACK_STATUS codes:

Return code Description
FLT_PREOP_COMPLETE
 FltOplockBreakH encountered a pool allocation failure, or a call to the FsRtlOplockBreakH function returned an error. FltOplockBreakH will set the error code in the Status member of the IO_STATUS_BLOCK structure. The IO_STATUS_BLOCK structure is specified in the IoStatus member of the FLT_CALLBACK_DATA callback data structure. The CallbackData parameter points to this FLT_CALLBACK_DATA.
FLT_PREOP_PENDING
 An oplock break was initiated, which caused the Filter Manager to post the I/O operation to a work queue. The I/O operation is represented by the callback data that the CallbackData parameter points to.
FLT_PREOP_SUCCESS_WITH_CALLBACK
 The callback data that the CallbackData parameter points to was not pended, and the I/O operation was performed immediately. Be aware that if the caller specified OPLOCK_FLAG_COMPLETE_IF_OPLOCKED in the Flags parameter, an oplock break might actually be in progress even though the I/O operation was not pended. To determine whether this is the situation, the caller should check for STATUS_OPLOCK_BREAK_IN_PROGRESS in the Status member of the IO_STATUS_BLOCK structure. The IO_STATUS_BLOCK structure is specified in the IoStatus member of the FLT_CALLBACK_DATA callback data structure.

Remarks

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

Requirements

Requirement Value
Minimum supported client The FltOplockBreakH routine is available starting with Windows 7.
Target Platform Universal
Header fltkernel.h (include Fltkernel.h)
Library FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

See also

FLT_CALLBACK_DATA

FltInitializeOplock

FsRtlOplockBreakH

IO_STATUS_BLOCK