Función FsRtlCheckOplockEx2 (ntifs.h)

Artículo
12/21/2024

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 opque oplock 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 controlador de filtro o sistema de archivos establece bits para especificar el comportamiento de FsRtlCheckOplockEx2. marcas tiene 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 de . FsRtlCheckOplockEx2 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 interbloqueo. Se admite a partir de Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Especifica que FsRtlCheckOplockEx2 debe revertir cualquier estado que se configuró anteriormente 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. 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 del 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. Especificar esta marca puede dar lugar a 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

Reservado; debe establecerse en cero.

[in, optional] CompletionRoutineContext

Puntero a la información de contexto definida por el llamador 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 se puede NULL.

[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 interbloqueo en curso, se llama a esta rutina cuando se completa la interrupción. Este parámetro es opcional y se puede 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.

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:

Context: puntero de información de contexto que se pasó en el parámetro Context de 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 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.

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 de 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) para 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. Este valor se omite a menos que se cumplan las siguientes condiciones: 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 se puede NULL.

[in, optional] NotifyRoutine

Puntero a una rutina de devolución de llamada proporcionada por el autor de la llamada que se va a llamar para la notificación de estado de interbloqueo. Este parámetro es opcional y se puede 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 del interbloqueo. 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 interbloqueo. 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 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 de interbloqueo. Si CompletionRoutine es null, bloquea FsRtlCheckOplockEx2 mientras se procesa el interbloqueo de oplock en lugar de devolver STATUS_PENDING. STATUS_PENDING es un código correcto.

Observaciones

Los minifiltros deben llamar a FltCheckOplockEx en lugar de FsRtlCheckOplockEx2.

FsRtlCheckOplockEx2 sincroniza el IRP de una operación de E/S 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 de operación y se haya especificado una rutina de finalización en se especificó el CompleteRoutine, FsRtlCheckOplockEx 2 devuelve STATUS_PENDING y llama a la rutina de devolución de llamada especificada en PostIrpRoutine. Cuando se ha confirmado la interrupción del 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 especificó completionRoutine, el subproceso del autor de la llamada se bloquea y FsRtlCheckOplockEx2 solo se 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 finaliza 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.

Solo se debe especificar un postIrpRoutine si se ha especificado un CompletionRoutine de . Cuando PostIrpRoutine no es NULL, se llama a antes de que se pone en cola cualquier cosa en la cola de Irp en espera.

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

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