Función FsRtlCheckOplockEx2 (ntifs.h)

Artículo
08/07/2023

FsRtlCheckOplockEx2 sincroniza el IRP de una operación de E/S de archivo con el estado actual de bloqueo oportunista (oplock) del archivo.

Sintaxis

NTSTATUS FsRtlCheckOplockEx2(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in]           ULONG                         FlagsEx2,
  [in, optional] PVOID                         CompletionRoutineContext,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine,
  [in]           ULONGLONG                     Timeout,
  [in, optional] PVOID                         NotifyContext,
  [in, optional] POPLOCK_NOTIFY_ROUTINE        NotifyRoutine
);

Parámetros

[in] Oplock

Puntero a la estructura oplock oppac del archivo. Este puntero debe haberse inicializado mediante una llamada anterior a FsRtlInitializeOplock.

[in] Irp

Puntero al IRP que declara la operación de E/S solicitada.

[in] Flags

Máscara de bits para la operación de E/S de archivo asociada. Un sistema de archivos o un controlador de filtro establece bits para especificar el comportamiento de FsRtlCheckOplockEx2. Las marcas tienen las siguientes opciones:

Valor de marca	Significado
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Especifica que se permite que una interrupción de interbloqueo continúe sin bloquear o pendiente la operación que provocó la interrupción del interbloqueo de operación.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Especifica que FsRtlCheckOplockEx2 solo debe comprobar si hay una clave de interbloqueo en el FILE_OBJECT asociado al IRP al que apunta el parámetro Irp . FsRtlCheckOplockEx2 debe agregar la clave si se proporciona una en irP. No se produce ningún otro procesamiento de interbloqueo; es decir, no se producirá ninguna interrupción de interbloqueo. Se admite a partir de Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Especifica que FsRtlCheckOplockEx2 debe revertir cualquier estado configurado previamente mediante una llamada a la rutina FsRtlOplockFsctrl . Se llama a FsRtlOplockFsctrl durante el procesamiento de una solicitud de IRP_MJ_CREATE que 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. Se admite a partir de Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Especifica para permitir que todos los saltos de interbloqueo continúen independientemente de la clave de interbloqueo. Se admite a partir de Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Especifica que Oplock está asociado al elemento primario (directorio) del archivo o directorio al que se dirige el IRP en el parámetro Irp . Se admite a partir de Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Especifica que la operación de E/S especificada en Irp es un IRP_MJ_CLEANUP para un identificador que se abrió originalmente con la marca FILE_DELETE_ON_CLOSE establecida en sus opciones de creación. Esta marca no tiene ningún efecto si Irp no es una operación de IRP_MJ_CLEANUP. Si se especifica esta marca, se puede producir una interrupción de interbloqueo. Se admite a partir de Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Especifica el control de una interrupción de interbloqueo en un directorio primario al eliminar un archivo o vínculo en ese directorio. Si se especifica, esta marca debe combinarse con OPLOCK_FLAG_PARENT_OBJECT. Esta marca debe especificarse cuando el sistema de archivos está procesando una operación que da lugar a la eliminación de un vínculo o archivo. Se admite a partir de Windows 8.

[in] FlagsEx2

Reservados; debe establecerse en cero.

[in, optional] CompletionRoutineContext

Puntero a la información de contexto definida por el autor de la llamada que se va a pasar a la rutina de devolución de llamada a la que apunta el parámetro CompletionRoutine . Este parámetro es opcional y puede ser NULL.

[in, optional] CompletionRoutine

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

CompletionRoutine se declara de la siguiente manera:

typedef VOID
(*POPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PVOID Context,
      IN PIRP Irp
      );

CompletionRoutine tiene los parámetros siguientes:

Contexto: puntero de información de contexto que se pasó en el parámetro Context a FsRtlCheckOplockEx2.
Irp: puntero al IRP para la operación de E/S.

[in, optional] PostIrpRoutine

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

PostIrpRoutine se declara de la siguiente manera:

typedef VOID
(*POPLOCK_FS_PREPOST_IRP) (
      IN PVOID Context,
      IN PIRP Irp
      );

PostIrpRoutine tiene los parámetros siguientes:

Context, que es un puntero de información de contexto que se pasó en el parámetro Context a FsRtlCheckOplockEx2.
Irp: puntero al IRP para la operación de E/S.

[in] Timeout

Si no es cero, especifica un tiempo de espera (en milisegundos) que se esperará en un evento usado para bloquear el subproceso del autor de la llamada para esperar a que se complete la interrupción de interbloqueo de operación. Este valor se omite a menos que se cumplan las dos condiciones siguientes: CompletionRoutine es NULL y NotifyRoutine no es NULL.

[in, optional] NotifyContext

Puntero a una estructura de OPLOCK_NOTIFY_PARAMS que se va a pasar a la rutina de devolución de llamada a la que apunta el parámetro NotifyRoutine . Este parámetro es opcional y puede ser NULL.

[in, optional] NotifyRoutine

Puntero a una rutina de devolución de llamada proporcionada por el autor de llamada que se llamará para la notificación de estado de interbloqueo. Este parámetro es opcional y puede ser NULL.

NotifyRoutine se declara de la siguiente manera:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine tiene los parámetros siguientes:

NotifyParams, que se establece como el parámetro NotifyContext pasado a FsRtlCheckOplockEx2.

Valor devuelto

FsRtlCheckOplockEx2 devuelve STATUS_SUCCESS o un código NTSTATUS adecuado, como uno de los siguientes:

Código devuelto	Descripción
STATUS_CANCELLED	Se canceló el IRP. STATUS_CANCELLED es un código de error.
STATUS_CANNOT_BREAK_OPLOCK	No se puede realizar la interrupción de interbloqueo. IrP es una solicitud de IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK se especificó en el parámetro create options para la operación y hay un oplock concedido.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Hay una interrupción de interbloqueo en curso. IRP es una solicitud de IRP_MJ_CREATE y FILE_COMPLETE_IF_OPLOCKED se especificó en el parámetro create options para la operación. STATUS_OPLOCK_BREAK_IN_PROGRESS es un código correcto que se devuelve si se estableció OPLOCK_FLAG_COMPLETE_IF_OPLOCKED y se ha interrumpido un interbloqueo.
STATUS_PENDING	Se está llevando a cabo una interrupción de interbloqueo y el control del IRP se pasó al paquete oplock. Si CompletionRoutine es NULL, FsRtlCheckOplockEx2 se bloquea mientras se procesa la interrupción de interbloqueo de operación en lugar de devolver STATUS_PENDING. STATUS_PENDING es un código correcto.

Comentarios

Los minifiltros deben llamar a FltCheckOplockEx en lugar de FsRtlCheckOplockEx2.

FsRtlCheckOplockEx2 sincroniza el IRP de una operación de E/S con el estado de interbloqueo actual de un archivo según las condiciones siguientes:

Si la operación de E/S hará que el interbloqueo se interrumpa, se inicia la interrupción de interbloqueo.
Si la operación de E/S no puede continuar hasta que se complete la interrupción del interbloqueo de operación y se haya especificado una rutina de finalización en CompletionRoutine , FsRtlCheckOplockEx2 devuelve STATUS_PENDING y llama a la rutina de devolución de llamada especificada en PostIrpRoutine. Cuando se ha confirmado la interrupción de interbloqueo, se llama a la rutina de devolución de llamada en CompletionRoutine .
Si la operación de E/S no puede continuar hasta que se complete la interrupción del interbloqueo de operación y no se haya especificado CompletionRoutine , el subproceso del autor de la llamada se bloqueará y FsRtlCheckOplockEx2 solo devolverá cuando se complete la interrupción del interbloqueo de operación.

Si el subproceso del autor de la llamada está bloqueado y NotifyRoutine no es NULL, se llamará a NotifyRoutine por cualquiera de los siguientes motivos establecidos en NotifyParams:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

La llamada a NotifyRoutine por cualquiera de los motivos anteriores solo se produce si CompletionRoutine es NULL y es necesario bloquear el subproceso del autor de la llamada para esperar a que se complete la interrupción.

Si se invoca NotifyRoutine por motivos OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, siempre se invocará por motivos OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED si la espera finaliza o se completa por cualquier motivo (que puede ser nunca).

FsRtlCheckOplockEx2 omite los códigos de estado de OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT y OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED devueltos por NotifyRoutine.

Una propiedad PostIrpRoutine solo debe especificarse si se ha especificado un Objeto CompletionRoutine . Cuando PostIrpRoutine no es NULL, se llama a antes de que todo se pone en cola a la cola de Irp en espera.

Si se especifica la marca de OPLOCK_FLAG_PARENT_OBJECT en Marcas, FsRtlCheckOplockEx2 interrumpirá incondicionalmente cualquier interbloqueo primario existente; es decir, no se tiene en cuenta el código principal de Irp .

Si un sistema de archivos usa oplocks, debe llamar a FsRtlCheckOplockEx2 desde cualquier rutina de envío para las operaciones de E/S que puedan provocar interrupciones de interbloqueo. Esta regla se aplica a los siguientes tipos de operaciones de E/S, ya que estas operaciones pueden provocar interrupciones de interbloqueo: