Função FsRtlCheckOplockEx2 (ntifs.h)

Artigo
12/21/2024

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 do arquivo associado. Um sistema de arquivos ou driver de filtro define bits para especificar o comportamento de FsRtlCheckOplockEx2. Flags tem as seguintes opções:

Valor do 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 verificar apenas uma chave oplock no FILE_OBJECT associado ao IRP para o qual o parâmetro irp aponta. FsRtlCheckOplockEx2 deverá adicionar a chave se uma for fornecida no IRP. Nenhum outro processamento oplock ocorre; ou seja, nenhuma quebra 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 foi configurado anteriormente por meio de uma chamada para a rotina de 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 de opções de criação. 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 em irp é um IRP_MJ_CLEANUP para um identificador que foi originalmente aberto com o sinalizador de 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

Reservado; 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 à 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.

de CompletionRoutine é declarado da seguinte maneira:

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

de CompletionRoutine tem os seguintes parâmetros:

Context: um ponteiro de informações de contexto que foi passado no parâmetro de Contexto 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:

Context, que é um ponteiro de informações de contexto que foi passado no parâmetro de Contexto 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 interrupção do oplock. Esse valor é ignorado, a menos que ambas as seguintes condições sejam verdadeiras: de 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 à 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 está definido como o parâmetro NotifyContext passado para FsRtlCheckOplockEx2.

Valor de retorno

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 de opções de criação para a operação e há um oplock concedido.
STATUS_OPLOCK_BREAK_IN_PROGRESS	Uma quebra de oplock está em andamento. O IRP é uma solicitação IRP_MJ_CREATE e FILE_COMPLETE_IF_OPLOCKED foi especificado no parâmetro de opções de criação 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, blocos FsRtlCheckOplockEx2 enquanto a quebra de oplock é processada em vez de retornar STATUS_PENDING. STATUS_PENDING é um código de sucesso.

Observações

Os minifiltros devem chamar FltCheckOplockEx em vez de FsRtlCheckOplockEx2 .

FsRtlCheckOplockEx2 sincroniza o IRP para uma operação de E/S com o estado 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 no completionRoutine foi especificada, FsRtlCheckOplockEx2 retornará STATUS_PENDING e chamará a rotina de retorno de chamada especificada em PostIrpRoutine . Quando a interrupção do oplock for 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 de CompletionRoutine não tiver sido especificada, o thread do chamador será bloqueado e FsRtlCheckOplockEx2 retornará somente quando a interrupção do oplock for concluída.

Se o thread do chamador estiver bloqueado e NotifyRoutine não estiver NULL, NotifyRoutine será chamado para qualquer um 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 de 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, ele sempre será invocado 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 de status OPLOCK_NOTIFY_BREAK_WAIT_INTERIM_TIMEOUT e OPLOCK_NOTIFY_BREAK_WAIT_TERMINATED retornados por NotifyRoutine.

Um PostIrpRoutine deve ser especificado somente se um de CompletionRoutine tiver sido especificado. 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 Flags, 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: