Función FsRtlCheckOplock (ntifs.h)

Artículo
12/21/2024

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

Sintaxis

NTSTATUS FsRtlCheckOplock(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [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, 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 context a FsRtlCheckOplock.
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 context a FsRtlCheckOplock.
Irp	Puntero al IRP para la operación de E/S.

Valor devuelto

La rutina FsRtlCheckOplock 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	Si el IRP es un IRP_MJ_CREATE y FILE_OPEN_REQUIRING_OPLOCK se encuentra en CreateOptions del IRP, la rutina no iniciará una interrupción de un bloqueo oportunista existente, pero se producirá un error con STATUS_CANNOT_BREAK_OPLOCK.
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 correcto.
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

FsRtlCheckOplock 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, FsRtlCheckOplock devuelve STATUS_PENDING y llama a la rutina de devolución de llamada a la que apunta el parámetro PostIrpRoutine.

Si un sistema de archivos o un controlador de filtro usa bloqueos oportunistas, debe llamar a FsRtlCheckOplock 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 información detallada sobre bloqueos oportunistas, consulte la documentación de Windows SDK.

Los minifiltros deben llamar a fltCheckOplock en lugar de FsRtlCheckOplock.

Requisitos

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