Función FsRtlOplockFsctrlEx (ntifs.h)

Artículo
02/27/2024

La rutina FsRtlOplockFsctrlEx realiza varias operaciones de bloqueo oportunista (oplock) en nombre de un sistema de archivos o un controlador de filtro.

Sintaxis

NTSTATUS FsRtlOplockFsctrlEx(
  [in] POPLOCK Oplock,
  [in] PIRP    Irp,
  [in] ULONG   OpenCount,
  [in] ULONG   Flags
);

Parámetros

[in] Oplock

Puntero oplock oppac 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. Este parámetro es obligatorio y no puede ser NULL.

[in] OpenCount

Número de identificadores de usuario para el archivo, si se solicita un interbloqueo exclusivo. Establecer un valor distinto de cero para una solicitud de interbloqueo de nivel 2, R o RH indica que hay bloqueos de intervalo de bytes en el archivo. Para obtener información sobre los tipos de interbloqueo, consulte Información general sobre Oplock.

[in] Flags

Máscara de bits para las operaciones de interbloqueo asociadas. Un sistema de archivos o un controlador de filtro establece bits para especificar el comportamiento de FsRtlOplockFsctrlEx. Este parámetro tiene las siguientes opciones:

Marca	Significado
OPLOCK_FSCTRL_FLAG_ALL_KEYS_MATCH (0x00000001)	El sistema de archivos comprobó que todas las claves de interbloqueo de cualquier identificador abierto coinciden actualmente. Al especificar esta marca, se permite que el paquete de oplock conceda un interbloqueo de nivel RW o RWH cuando exista más de un identificador abierto para el archivo. Para obtener más información sobre los tipos de oplock, vea Información general sobre Oplock.

Valor devuelto

FsRtlOplockFsctrlEx devuelve uno de los siguientes valores NTSTATUS:

Código devuelto	Descripción
STATUS_SUCCESS	Para una solicitud de IRP_MJ_CREATE, STATUS_SUCCESS indica que se concedió el interbloqueo de filtro solicitado. Para una operación FSCTL, el significado de STATUS_SUCCESS depende del código FSCTL. Para obtener más información, vea las páginas de referencia de los códigos FSCTL enumerados en la siguiente sección Comentarios.
STATUS_CANCELLED	Se canceló la operación de E/S. STATUS_CANCELLED es un código de error.
STATUS_INVALID_PARAMETER	El código FSCTL para la operación de E/S no era uno de los valores válidos enumerados en la sección Comentarios siguiente. STATUS_INVALID_PARAMETER es un código de error.
STATUS_OPLOCK_NOT_GRANTED	No se pudo conceder el interbloqueo. STATUS_OPLOCK_NOT_GRANTED es un código de error.
STATUS_PENDING	Solo se usa para las operaciones FSCTL. El significado de STATUS_PENDING depende del código FSCTL. Para obtener más información, vea las páginas de referencia de los códigos FSCTL enumerados en la siguiente sección Comentarios. STATUS_PENDING es un código correcto.
STATUS_CANNOT_BREAK_OPLOCK	No se pudo conceder un nuevo interbloqueo. IRP es una solicitud de IRP_MJ_CREATE y FILE_OPEN_REQUIRING_OPLOCK se especificó en el parámetro create options para la operación. STATUS_CANNOT_BREAK_OPLOCK es un código correcto.

Comentarios

Los sistemas de archivos y los controladores de filtro heredados llaman a FsRtlOplockFsctrlEx para realizar diversas operaciones de interbloqueo para una operación de E/S de control de sistema de archivos o creación. Los minifiltros deben llamar a FltOplockFsctrlEx en lugar de FsRtlOplockFsctrlEx.

El IRP al que apunta el parámetro Irp debe ser un IRP válido para una operación de IRP_MJ_FILE_SYSTEM_CONTROL o IRP_MJ_CREATE .

Si irP es una solicitud de IRP_MJ_FILE_SYSTEM_CONTROL, FsRtlOplockFsctrlEx se puede usar con uno de los siguientes códigos FSCTL, que se establece en IrpSp-Parameters.FileSystemControl.FsControlCode>:

Para obtener más información sobre estos FSCTL y sobre bloqueos oportunistas en general, consulte la documentación de Microsoft Windows SDK.

Si irP es una solicitud de IRP_MJ_CREATE, se puede usar FsRtlOplockFsctrlEx para solicitar un interbloqueo de filtro pendiente si se cumplen todas las condiciones siguientes:

El valor del parámetro OpenCount debe ser 1.
El valor del parámetro DesiredAccess para la solicitud IRP_MJ_CREATE debe ser FILE_READ_ATTRIBUTES.
El valor del parámetro ShareAccess para la solicitud de IRP_MJ_CREATE debe ser FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Si se concede la solicitud de un interbloqueo de filtro pendiente, FsRtlOplockFsctrlEx devuelve STATUS_SUCCESS. Para obtener más información sobre la creación de parámetros, consulte la entrada de referencia para IRP_MJ_CREATE.

Los filtros y los sistemas de archivos que llaman a esta función deben sincronizar las llamadas al paquete de oplock proporcionado por el sistema. Consulte Sincronización de oplock para obtener más información.

Requisitos

Requisito	Value
Cliente mínimo compatible	La rutina FsRtlOplockFsctrlEx está disponible a partir de Windows 7.
Plataforma de destino	Universal
Encabezado	ntifs.h (incluya Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL