Función FsRtlCheckOplockEx (ntifs.h)

Artículo
12/20/2024

La rutina de 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 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 para permitir 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)	Se admite a partir de Windows 7. Especifica que FsRtlCheckOplockEx solo debe comprobar si hay una clave de bloqueo oportunista en la FILE_OBJECT asociada al IRP a la que apunta el parámetro irp de irp. FsRtlCheckOplockEx debe agregar la clave si se proporciona una en el IRP. 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)	Se admite a partir de Windows 7. Especifica que FsRtlCheckOplockEx debe revertir cualquier estado configurado previamente a través de una llamada a la rutina de FsRtlOplockFsctrl. se llama al 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.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Se admite a partir de Windows 7. Especifica para permitir 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 del 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 una interrupción 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 una interrupción 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
Contexto	Puntero de información de contexto que se pasó en el parámetro Context de 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 va a 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
Contexto	Puntero de información de contexto que se pasó en el parámetro Context de 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 IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK se especificó en el parámetro create options para la operación y hay un interbloqueo concedido.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Se está llevando a cabo una interrupción de bloqueo oportunista. IRP es una solicitud 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 de éxito 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 la interrupción del interbloqueo de operación, en lugar de devolver STATUS_PENDING. STATUS_PENDING es un código correcto.

Observaciones

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 del bloqueo oportunista y se haya especificado una rutina de finalización en se especificó el CompletionRoutine, FsRtlCheckOplockEx devuelve STATUS_PENDING y llama a la rutina de devolución de llamada especificada en PostIrpRoutine. Cuando se reconoce la interrupción del 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 volverá hasta que se confirme la interrupción del bloqueo oportunista.

Solo se debe especificar un postIrpRoutine si se ha especificado un CompletionRoutine de .

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 del SDK de Microsoft Windows.

Los minifiltros deben llamar a FltCheckOplockEx en lugar de FsRtlCheckOplockEx.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista
de la plataforma de destino de	Universal
encabezado de	ntifs.h (incluya Ntifs.h)
biblioteca de	NtosKrnl.lib
DLL de	NtosKrnl.exe
irQL	<= APC_LEVEL