Função FsRtlCheckOplock (ntifs.h)

Artigo
10/04/2023

A rotina FsRtlCheckOplock sincroniza o IRP para uma operação de E/S de arquivo com o estado atual de bloqueio oportunista (oplock) do arquivo.

Sintaxe

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

Um ponteiro de bloqueio oportunista opaco para o arquivo. Esse ponteiro deve ter sido inicializado por uma chamada anterior para FsRtlInitializeOplock.

[in] Irp

Um ponteiro para o IRP para a operação de E/S.

[in, optional] Context

Um ponteiro para informações de contexto definidas pelo chamador a serem passadas para as rotinas de retorno de chamada para as quais os parâmetros CompletionRoutine e PostIrpRoutine apontam.

[in, optional] CompletionRoutine

Um ponteiro para uma rotina de retorno de chamada fornecida pelo chamador. Se uma quebra de bloqueio oportunista estiver em andamento, essa rotina será chamada quando a interrupção for concluída. Esse parâmetro é opcional e pode ser NULL. Se for NULL, o chamador será colocado em um estado de espera até que a quebra de bloqueio oportunista seja concluída.

Essa rotina é declarada da seguinte maneira:

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

Essa rotina tem os seguintes parâmetros:

Parâmetro	Descrição
Contexto	Um ponteiro de informações de contexto que foi passado no parâmetro Context para FsRtlCheckOplock.
Irp	Um ponteiro para o IRP para a operação de E/S.

[in, optional] PostIrpRoutine

Um ponteiro para uma rotina de retorno de chamada fornecida pelo chamador a ser chamada se a operação de E/S for postada em uma fila de trabalho. Esse parâmetro é opcional e pode ser NULL.

Essa rotina é declarada da seguinte maneira:

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

Essa rotina tem os seguintes parâmetros:

Parâmetro	Descrição
Contexto	Um ponteiro de informações de contexto que foi passado no parâmetro Context para FsRtlCheckOplock.
Irp	Um ponteiro para o IRP para a operação de E/S.

Retornar valor

A rotina FsRtlCheckOplock retorna STATUS_SUCCESS ou um código NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_CANCELLED	O IRP foi cancelado. STATUS_CANCELLED é um código de erro.
STATUS_CANNOT_BREAK_OPLOCK	Se o IRP for um IRP_MJ_CREATE e FILE_OPEN_REQUIRING_OPLOCK estiver no CreateOptions do IRP, a rotina não iniciará uma quebra de um bloqueio oportunista existente, mas falhará com STATUS_CANNOT_BREAK_OPLOCK.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Uma quebra de bloqueio oportunista está em andamento. O IRP é uma solicitação IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED foi especificado no parâmetro criar opções para a operação. STATUS_OPLOCK_BREAK_IN_PROGRESS é um código de êxito.
STATUS_PENDING	Uma quebra de bloqueio oportunista foi iniciada e o controle do IRP foi passado para o pacote oplock. Se CompletionRoutine for NULL, essa rotina será bloqueada enquanto a interrupção do oplock for processada, em vez de retornar STATUS_PENDING. STATUS_PENDING é um código de êxito.

Comentários

FsRtlCheckOplock sincroniza o IRP para uma operação de E/S com o estado de bloqueio oportunista atual de um arquivo de acordo com as seguintes condições:

Se a operação de E/S fizer com que o bloqueio oportunista seja interrompido, a quebra de bloqueio oportunista será iniciada.
Se a operação de E/S não puder continuar até que a quebra de bloqueio oportunista seja concluída, FsRtlCheckOplock retornará STATUS_PENDING e chamará a rotina de retorno de chamada para a qual o parâmetro PostIrpRoutine aponta.

Se um sistema de arquivos ou driver de filtro usar bloqueios oportunistas, ele deverá chamar FsRtlCheckOplock de qualquer rotina de expedição para operações de E/S que possam causar quebras de bloqueio oportunistas. Essa regra se aplica aos seguintes tipos de operações de E/S, pois essas operações podem causar quebras de bloqueio 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 obter informações detalhadas sobre bloqueios oportunistas, consulte a documentação do SDK do Windows.

Os minifilters devem chamar FltCheckOplock em vez de FsRtlCheckOplock.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000
Plataforma de Destino	Universal
Cabeçalho	ntifs.h (inclua FltKernel.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL