Função FsRtlCheckOplockEx2 (ntifs.h)

Artigo
08/07/2023

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

Sintaxe

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

Ponteiro para a estrutura oplock opaca do arquivo. Esse ponteiro deve ter sido inicializado por uma chamada anterior para FsRtlInitializeOplock.

[in] Irp

Ponteiro para o IRP que declara a operação de E/S solicitada.

[in] Flags

Uma máscara de bits para a operação de E/S de arquivo associada. Um sistema de arquivos ou driver de filtro define bits para especificar o comportamento de FsRtlCheckOplockEx2. Os sinalizadores têm as seguintes opções:

Valor de sinalizador	Significado
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Especifica para permitir que uma quebra de oplock prossiga sem bloquear ou aguardar a operação que causou a interrupção do oplock.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Especifica que FsRtlCheckOplockEx2 deve marcar apenas para uma chave oplock no FILE_OBJECT associado ao IRP para o qual o parâmetro Irp aponta. FsRtlCheckOplockEx2 deve adicionar a chave se uma for fornecida no IRP. Nenhum outro processamento de oplock ocorre; ou seja, nenhuma interrupção de oplock ocorrerá. Com suporte a partir do Windows 7.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Especifica que FsRtlCheckOplockEx2 deve reverter qualquer estado que tenha sido configurado anteriormente por meio de uma chamada para a rotina FsRtlOplockFsctrl. FsRtlOplockFsctrl é chamado durante o processamento de uma solicitação de IRP_MJ_CREATE que especifica o sinalizador FILE_OPEN_REQUIRING_OPLOCK no parâmetro create options. O sinalizador OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK normalmente é usado no processamento final de tal solicitação de criação quando ele falhou anteriormente. Com suporte a partir do Windows 7.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Especifica para permitir que todas as quebras de oplock prossigam independentemente da chave oplock. Com suporte a partir do Windows 7.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Especifica que Oplock está associado ao pai (diretório) do arquivo ou diretório ao qual o IRP no parâmetro Irp é direcionado. Com suporte a partir do Windows 8.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Especifica que a operação de E/S especificada no Irp é uma IRP_MJ_CLEANUP para um identificador que foi originalmente aberto com o sinalizador FILE_DELETE_ON_CLOSE definido em suas opções de criação. Esse sinalizador não terá efeito se Irp não for uma operação de IRP_MJ_CLEANUP. Especificar esse sinalizador pode resultar em uma quebra de oplock. Com suporte a partir do Windows 8.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Especifica o tratamento de uma quebra de oplock em um diretório pai ao excluir um arquivo ou link nesse diretório. Se especificado, esse sinalizador deve ser combinado com OPLOCK_FLAG_PARENT_OBJECT. Esse sinalizador deve ser especificado quando o sistema de arquivos está processando uma operação que resulta na remoção de um link ou arquivo. Com suporte a partir do Windows 8.

[in] FlagsEx2

Reservados; deve ser definido como zero.

[in, optional] CompletionRoutineContext

Ponteiro para informações de contexto definidas pelo chamador a serem passadas para a rotina de retorno de chamada para a qual o parâmetro CompletionRoutine aponta. Esse parâmetro é opcional e pode ser NULL.

[in, optional] CompletionRoutine

Ponteiro para uma rotina de retorno de chamada fornecida pelo chamador. Se uma quebra de oplock 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, FsRtlCheckOpLockEx2 opera de forma síncrona, colocando o chamador em um estado de espera até que a interrupção do oplock seja concluída.

CompletionRoutine é declarada da seguinte maneira:

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

CompletionRoutine tem os seguintes parâmetros:

Contexto: um ponteiro de informações de contexto que foi passado no parâmetro Context para FsRtlCheckOplockEx2.
Irp: um ponteiro para o IRP para a operação de E/S.

[in, optional] PostIrpRoutine

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.

PostIrpRoutine é declarado da seguinte maneira:

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

PostIrpRoutine tem os seguintes parâmetros:

Contexto, que é um ponteiro de informações de contexto que foi passado no parâmetro Context para FsRtlCheckOplockEx2.
Irp: um ponteiro para o IRP para a operação de E/S.

[in] Timeout

Se não for zero, especificará um tempo limite (em milissegundos) para aguardar um evento usado para bloquear o thread do chamador para aguardar a conclusão da quebra de oplock. Esse valor é ignorado, a menos que ambas as seguintes condições sejam verdadeiras: CompletionRoutine é NULL e NotifyRoutine não é NULL.

[in, optional] NotifyContext

Ponteiro para uma estrutura OPLOCK_NOTIFY_PARAMS a ser passada para a rotina de retorno de chamada para a qual o parâmetro NotifyRoutine aponta. Esse parâmetro é opcional e pode ser NULL.

[in, optional] NotifyRoutine

Ponteiro para uma rotina de retorno de chamada fornecida pelo chamador a ser chamada para notificação de estado oplock. Esse parâmetro é opcional e pode ser NULL.

NotifyRoutine é declarado da seguinte maneira:

typedef NTSTATUS
(*POPLOCK_NOTIFY_ROUTINE) (
      IN POPLOCK_NOTIFY_PARAMS NotifyParams
      );

NotifyRoutine tem os seguintes parâmetros:

NotifyParams, que é definido como o parâmetro NotifyContext passado para FsRtlCheckOplockEx2.

Retornar valor

FsRtlCheckOplockEx2 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	A quebra de oplock não pode ser realizada. O IRP é uma solicitação IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK foi especificado no parâmetro create options para a operação e há um oplock concedido.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Um intervalo de oplock está em andamento. O IRP é uma solicitação IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED foi especificado no parâmetro create options para a operação. STATUS_OPLOCK_BREAK_IN_PROGRESS é um código de êxito retornado se OPLOCK_FLAG_COMPLETE_IF_OPLOCKED foi definido e um oplock foi interrompido.
STATUS_PENDING	Uma quebra de oplock está em andamento e o controle do IRP foi passado para o pacote oplock. Se CompletionRoutine for NULL, FsRtlCheckOplockEx2 será bloqueado enquanto a quebra de oplock for processada em vez de retornar STATUS_PENDING. STATUS_PENDING é um código de êxito.

Comentários

Os minifiltros devem chamar FltCheckOplockEx em vez de FsRtlCheckOplockEx2.

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

Se a operação de E/S fizer com que o oplock seja interrompido, a interrupção do oplock será iniciada.
Se a operação de E/S não puder continuar até que a interrupção do oplock seja concluída e uma rotina de conclusão em CompletionRoutine tenha sido especificada, FsRtlCheckOplockEx2 retornará STATUS_PENDING e chamará a rotina de retorno de chamada especificada em PostIrpRoutine. Quando a interrupção do oplock é confirmada, a rotina de retorno de chamada em CompletionRoutine é chamada.
Se a operação de E/S não puder continuar até que a interrupção do oplock seja concluída e CompletionRoutine não tenha sido especificada, o thread do chamador será bloqueado e FsRtlCheckOplockEx2 retornará somente quando a quebra de oplock for concluída.

Se o thread do chamador estiver bloqueado e NotifyRoutine não for NULL, NotifyRoutine será chamado por qualquer ou todos os seguintes motivos definidos em NotifyParams:

OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT
OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED

A chamada para NotifyRoutine por qualquer um dos motivos acima ocorre somente se CompletionRoutine for NULL e for necessário bloquear o thread do chamador para aguardar a conclusão da interrupção.

Se NotifyRoutine for invocado por motivo OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT, ela sempre será invocada por motivo OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED se a espera for encerrada/concluída por qualquer motivo (o que pode nunca ser).

FsRtlCheckOplockEx2 ignora os códigos OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT e OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED status retornados por NotifyRoutine.

Uma PostIrpRoutine só deverá ser especificada se uma CompletionRoutine tiver sido especificada. Quando PostIrpRoutine não é NULL, ele é chamado antes de qualquer coisa ser enfileirada na fila de Irp em espera.

Se o sinalizador OPLOCK_FLAG_PARENT_OBJECT for especificado em Sinalizadores, FsRtlCheckOplockEx2 interromperá incondicionalmente qualquer oplock pai existente; ou seja, o código principal no Irp não é considerado.

Se um sistema de arquivos usar oplocks, ele deverá chamar FsRtlCheckOplockEx2 de qualquer rotina de expedição para operações de E/S que possam causar quebras de oplock. Essa regra se aplica aos seguintes tipos de operações de E/S, pois essas operações podem causar quebras de oplock: