Função FsRtlCheckOplockEx (ntifs.h)

Artigo
09/27/2023

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

Sintaxe

NTSTATUS FsRtlCheckOplockEx(
  [in]           POPLOCK                       Oplock,
  [in]           PIRP                          Irp,
  [in]           ULONG                         Flags,
  [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] 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 FsRtlCheckOplockEx. O parâmetro Flags tem as seguintes opções:

Valor	Significado
OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)	Especifica para permitir que uma quebra de bloqueio oportunista prossiga sem bloquear ou aguardar a operação que causou a interrupção do oplock.
OPLOCK_FLAG_OPLOCK_KEY_CHECK_ONLY (0x00000002)	Com suporte a partir do Windows 7. Especifica que FsRtlCheckOplockEx só deve marcar para uma chave de bloqueio oportunista no FILE_OBJECT associada ao IRP para o qual o parâmetro Irp aponta. FsRtlCheckOplockEx deverá adicionar a chave se uma for fornecida no IRP. Nenhum outro processamento oplock ocorre; ou seja, nenhuma quebra de bloqueio oportunista ocorrerá.
OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)	Com suporte a partir do Windows 7. Especifica que FsRtlCheckOplockEx 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 dessa solicitação de criação quando ele falhou anteriormente.
OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)	Com suporte a partir do Windows 7. Especifica para permitir que todas as quebras de bloqueio oportunistas prossigam independentemente da chave de bloqueio oportunista.
OPLOCK_FLAG_PARENT_OBJECT (0x00000010)	Com suporte começando com Windows 8. Especifica que o Oplock está associado ao pai (diretório) do arquivo ou diretório ao qual o IRP no parâmetro Irp é direcionado.
OPLOCK_FLAG_CLOSING_DELETE_ON_CLOSE (0x00000020)	Com suporte começando com Windows 8. 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 bloqueio oportunista.
OPLOCK_FLAG_REMOVING_FILE_OR_LINK (0x00000040)	Com suporte começando com Windows 8. Especifica o tratamento de uma quebra de bloqueio oportunista 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.

[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 FsRtlCheckOplockEx.
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 FsRtlCheckOplockEx.
Irp	Um ponteiro para o IRP para a operação de E/S.

Retornar valor

FsRtlCheckOplockEx 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 bloqueio oportunista (oplock) não pode ser realizada. O IRP é uma solicitação IRP_MJ_CREATE. FILE_OPEN_REQUIRING_OPLOCK foi especificado no parâmetro criar opções para a operação e há um oplock concedido.
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 retornado se OPLOCK_FLAG_COMPLETE_IF_OPLOCKED foi definido e um bloqueio oportunista foi quebrado.
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

FsRtlCheckOplockEx 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 e uma rotina de conclusão em CompletionRoutine tiver sido especificada, FsRtlCheckOplockEx retornará STATUS_PENDING e chamará a rotina de retorno de chamada especificada em PostIrpRoutine. Quando a quebra de bloqueio oportunista é reconhecida, a rotina de retorno de chamada em CompletionRoutine é chamada.
Se a operação de E/S não puder continuar até que a quebra de bloqueio oportunista seja concluída e CompletionRoutine não tiver sido especificada, FsRtlCheckOplockEx não retornará até que a quebra de bloqueio oportunista seja confirmada.

Uma PostIrpRoutine só deverá ser especificada se uma CompletionRoutine tiver sido especificada.

Se um sistema de arquivos ou driver de filtro usar bloqueios oportunistas, ele deverá chamar FsRtlCheckOplockEx 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 mais informações sobre bloqueios oportunistas, consulte a documentação do SDK do Microsoft Windows.

Minifilters devem chamar FltCheckOplockEx em vez de FsRtlCheckOplockEx.

Requisitos

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