Función FltCheckOplockEx (fltkernel.h)

Artículo
12/21/2024

Un controlador de minifiltro llama a la rutina FltCheckOplockEx para sincronizar la estructura de datos de devolución de llamada para una operación de E/S de archivo basada en IRP que tenga el estado actual de bloqueo oportunista (oplock) del archivo.

Sintaxis

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
);

Parámetros

[in] Oplock

Puntero oplock opaco para el archivo. Este puntero debe haberse inicializado mediante una llamada anterior a FltInitializeOplock.

[in] CallbackData

Puntero a los datos de devolución de llamada FLT_CALLBACK_DATAestructura para la operación de E/S.

[in] Flags

Máscara de bits para la operación de E/S de archivo asociada. Un controlador de minifiltro establece bits para especificar el comportamiento de FltCheckOplockEx. El parámetro Flags tiene las siguientes opciones:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Permite que una interrupción de bloqueo oportunista continúe sin bloquear o pendiente la operación que provocó la interrupción del bloqueo de operación.

OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)

Especifica que fltCheckOplockEx solo debe comprobar si hay una clave de bloqueo oportunista en la FILE_OBJECT asociada a la operación de E/S. Estas operaciones de E/S se representan mediante los datos de devolución de llamada a los que apunta el parámetro CallbackData. fltCheckOplockEx debe agregar la clave si se proporciona una en la operación de E/S. No se produce ningún otro procesamiento de interbloqueos; es decir, no se producirá ninguna interrupción de bloqueo oportunista.

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

Especifica que FsRtlCheckOplockEx debe revertir cualquier estado configurado previamente a través de una llamada a la rutina de FltOplockFsctrl. se llama a fltOplockFsctrl cuando se procesa una solicitud de IRP_MJ_CREATE. Esta solicitud IRP_MJ_CREATE especifica la marca FILE_OPEN_REQUIRING_OPLOCK en el parámetro create options. La marca OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK se usa normalmente en el procesamiento final de dicha solicitud de creación cuando se produjo un error anteriormente.

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Permite que todos los saltos de bloqueo oportunistas continúen independientemente de la clave de bloqueo oportunista.

[in, optional] Context

Puntero a la información de contexto definida por el autor de la llamada que se va a pasar a las rutinas de devolución de llamada a las que WaitCompletionRoutine y PrePostCallbackDataRoutine apuntar. El Administrador de filtros trata esta información como opaca.

[in, optional] WaitCompletionRoutine

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. Si hay una interrupción de interbloqueo en curso, el Administrador de filtros llama a esta rutina cuando se completa la interrupción del interbloqueo. Este parámetro es opcional y se puede NULL. Si es NULL, el autor de la llamada se coloca en un estado de espera hasta que se complete la interrupción del interbloqueo de operación.

Esta rutina se declara de la siguiente manera:

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

Esta rutina tiene los parámetros siguientes:

CallbackData

Puntero a la estructura de datos de devolución de llamada para la operación de E/S.

Nota que cuando se llama al WaitCompleteRoutine, la subestructura de IoStatus podría rellenarse con un estado de error (por ejemplo, STATUS_CANCELLED). Debe inspeccionar este estado y reaccionar adecuadamente.

Contexto

Puntero de información de contexto que se pasó en el parámetro Context a FltCheckOplockEx.

[in, optional] PrePostCallbackDataRoutine

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada que se va a llamar si la operación de E/S se publica en una cola de trabajo. Este parámetro es opcional y se puede NULL.

Esta rutina se declara de la siguiente manera:

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

CallbackData

Puntero a la estructura de datos de devolución de llamada para la operación de E/S.

Contexto

Puntero de información de contexto que se pasó en el parámetro Context a FltCheckOplockEx.

Valor devuelto

fltCheckOplockEx devuelve uno de los siguientes códigos de FLT_PREOP_CALLBACK_STATUS:

Código devuelto	Descripción
FLT_PREOP_COMPLETE	fltCheckOplockEx encontró un error de asignación de grupo o una llamada a la función FsRtlCheckOplockEx devolvió un error. FltCheckOplockEx establece el código de error en el miembro status de la estructura de IO_STATUS_BLOCK del miembro ioStatus de la estructura de datos de devolución de llamada de FLT_CALLBACK_DATA. El parámetro CallbackData apunta a esta estructura de FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Se inició una interrupción de interbloqueo, lo que provocó que el Administrador de filtros publicara la operación de E/S en una cola de trabajo. La operación de E/S se representa mediante los datos de devolución de llamada a los que apunta el parámetro callbackData .
FLT_PREOP_SUCCESS_WITH_CALLBACK	Los datos de devolución de llamada a los que apunta el parámetro CallbackData apunta a no se han lápiz y la operación de E/S se realizó inmediatamente. Tenga en cuenta que si el autor de la llamada especificó OPLOCK_FLAG_COMPLETE_IF_OPLOCKED en el parámetro Flags, una interrupción de interbloqueo podría estar en curso aunque la operación de E/S no estuviera en curso. Para determinar si se trata de esta situación, el autor de la llamada debe comprobar si hay STATUS_OPLOCK_BREAK_IN_PROGRESS en el miembro estado de de la estructura de IO_STATUS_BLOCK del miembro IoStatus de la estructura de datos de devolución de llamada de FLT_CALLBACK_DATA.

Observaciones

Un controlador de minifiltro llama a fltCheckOplockEx para sincronizar una operación de E/S basada en IRP con el estado actual de interbloqueo de un archivo según las condiciones siguientes:

Si la operación de E/S hará que se interrumpa el interbloqueo, se inicia la interrupción del interbloqueo.
Si la operación de E/S no puede continuar hasta que se complete la interrupción del interbloqueo, fltCheckOplockEx devuelve FLT_PREOP_PENDING y llama a la rutina de devolución de llamada a la que apunta el parámetro PrePostCallbackDataRoutine.
Si un controlador de minifiltro usa interbloqueos, debe llamar a FltCheckOplockEx desde cualquier rutina de devolución de llamada de preoperación (PFLT_PRE_OPERATION_CALLBACK) para las operaciones de E/S que pueden provocar interrupciones de oplock. Esta regla se aplica a los siguientes tipos de operaciones de E/S, ya que estas operaciones pueden provocar interrupciones de interbloqueo:
- 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

La operación de E/S debe ser una operación de E/S basada en IRP. Para determinar si una estructura de datos de devolución de llamada determinada representa una operación de E/S basada en IRP, use la macro FLT_IS_IRP_OPERATION.

Los minifiltros no deben llamar a FltCheckOplockEx de nuevo dentro de la devolución de llamada especificada en WaitCompletionRoutine. Si lo hace, se puede producir una condición de interbloqueo si el paquete de interbloqueo llama a la devolución de llamada de finalización antes de FltCheckOplockEx devuelve.

Para obtener más información sobre los bloqueos oportunistas, consulte la documentación del SDK de Microsoft Windows.

Requisitos

Requisito	Valor
cliente mínimo admitido	La rutina FltCheckOplockEx está disponible a partir de Windows 7.
de la plataforma de destino de	Universal
encabezado de	fltkernel.h (incluya Fltkernel.h)
biblioteca de	FltMgr.lib
irQL	<= APC_LEVEL