Función FsRtlCheckOplockEx (ntifs.h)

Artículo
10/04/2023

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

Sintaxis

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [in, optional] PVOID                         Context,
  [in, optional] POPLOCK_WAIT_COMPLETE_ROUTINE CompletionRoutine,
  [in, optional] POPLOCK_FS_PREPOST_IRP        PostIrpRoutine
);

Parámetros

[in] Oplock

Puntero de bloqueo oportunista opaco para el archivo. Este puntero debe haberse inicializado mediante una llamada anterior a FsRtlInitializeOplock.

[in] Irp

Puntero al IRP para la operación de E/S.

[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 FsRtlCheckOplockEx. El parámetro Flags tiene las siguientes opciones:

Valor	Significado
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Especifica que se permite que una interrupción de bloqueo oportunista continúe sin bloquear o pendiente la operación que provocó la interrupción del interbloqueo.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Se admite a partir de Windows 7. Especifica que FsRtlCheckOplockEx solo debe comprobar si hay una clave de bloqueo oportunista en el FILE_OBJECT asociado al IRP al que apunta el parámetro Irp . FsRtlCheckOplockEx debe agregar la clave si se proporciona una en el IRP. No se produce ningún otro procesamiento de interbloqueo; es decir, no se producirá ninguna interrupción de bloqueo oportunista.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Se admite a partir de Windows 7. Especifica que FsRtlCheckOplockEx debe revertir cualquier estado configurado anteriormente a través de 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 de 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)	Se admite a partir de Windows 7. Especifica que todos los saltos de bloqueo oportunistas continúen independientemente de la clave de bloqueo oportunista.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Se admite a partir de Windows 8. Especifica que Oplock está asociado al elemento primario (directorio) del archivo o directorio al que se dirige el IRP en el parámetro Irp .
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Se admite a partir de Windows 8. 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. Especificar esta marca puede dar lugar a una interrupción de bloqueo oportunista.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Se admite a partir de Windows 8. Especifica el control de un salto de bloqueo oportunista 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.

[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 apuntan los parámetros CompletionRoutine y PostIrpRoutine .

[in, optional] CompletionRoutine

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada. Si hay un salto de bloqueo oportunista 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, el autor de la llamada se coloca en un estado de espera hasta que se complete la interrupción de bloqueo oportunista.

Esta rutina se declara de la siguiente manera:

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

Esta rutina tiene los parámetros siguientes:

Parámetro	Descripción
Context	Puntero de información de contexto que se pasó en el parámetro Context a FsRtlCheckOplockEx.
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.

Esta rutina se declara de la siguiente manera:

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

Esta rutina tiene los parámetros siguientes:

Parámetro	Descripción
Context	Puntero de información de contexto que se pasó en el parámetro Context a FsRtlCheckOplockEx.
Irp	Puntero al IRP para la operación de E/S.

Valor devuelto

FsRtlCheckOplockEx 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 del bloqueo oportunista (oplock). 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	Se está llevando a cabo una interrupción de bloqueo oportunista. 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 roto un bloqueo oportunista.
STATUS_PENDING	Se ha iniciado una interrupción de bloqueo oportunista y se ha pasado el control del IRP al paquete oplock. Si CompletionRoutine es NULL, esta rutina se bloqueará mientras se procesa el interbloqueo de operación, en lugar de devolver STATUS_PENDING. STATUS_PENDING es un código correcto.

Comentarios

FsRtlCheckOplockEx sincroniza el IRP para una operación de E/S con el estado de bloqueo oportunista actual de un archivo según las condiciones siguientes:

Si la operación de E/S hará que se interrumpa el bloqueo oportunista, se inicia la interrupción del bloqueo oportunista.
Si la operación de E/S no puede continuar hasta que se complete la interrupción de bloqueo oportunista y se haya especificado una rutina de finalización en CompletionRoutine , FsRtlCheckOplockEx devuelve STATUS_PENDING y llama a la rutina de devolución de llamada especificada en PostIrpRoutine. Cuando se ha confirmado el salto de bloqueo oportunista, 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 bloqueo oportunista y no se haya especificado CompletionRoutine , FsRtlCheckOplockEx no devolverá hasta que se confirme la interrupción de bloqueo oportunista.

Una propiedad PostIrpRoutine solo debe especificarse si se ha especificado un Objeto CompletionRoutine .

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

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

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

Los minifiltros deben llamar a FltCheckOplockEx en lugar de FsRtlCheckOplockEx.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows Vista
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL