Função FltCheckOplock (fltkernel.h)

Artigo
02/26/2024

Um driver de minifiltro chama FltCheckOplock para sincronizar a estrutura de dados de retorno de chamada para uma operação de E/S de arquivo baseada em IRP com o estado atual de bloqueio oportunista (oplock) do arquivo.

Sintaxe

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplock(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in, optional] PVOID                                   Context,
  [in, optional] PFLTOPLOCK_WAIT_COMPLETE_ROUTINE        WaitCompletionRoutine,
  [in, optional] PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE PrePostCallbackDataRoutine
);

Parâmetros

[in] Oplock

Um ponteiro oplock oplock opaco para o arquivo. Esse ponteiro deve ter sido inicializado por uma chamada anterior para FltInitializeOplock.

[in] CallbackData

Um ponteiro para a estrutura de dados de retorno de chamada (FLT_CALLBACK_DATA) 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 WaitCompletionRoutine e PrePostCallbackDataRoutine apontam. O Gerenciador de Filtros trata essas informações como opacas.

[in, optional] WaitCompletionRoutine

Um ponteiro para uma rotina de retorno de chamada fornecida pelo chamador. Se uma quebra de oplock estiver em andamento, o Gerenciador de Filtros chamará essa rotina quando a interrupção do oplock 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 do oplock seja concluída.

Essa rotina é declarada da seguinte maneira:

typedef VOID
(*PFLTOPLOCK_WAIT_COMPLETE_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

Essa rotina tem os seguintes parâmetros:

Callbackdata

Ponteiro para a estrutura de dados de retorno de chamada para a operação de E/S.

Contexto

Um ponteiro de informações de contexto que foi passado no parâmetro Context para FltCheckOplock.

[in, optional] PrePostCallbackDataRoutine

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
(*PFLTOPLOCK_PREPOST_CALLBACKDATA_ROUTINE) (
      IN PFLT_CALLBACK_DATA CallbackData,
      IN PVOID Context
      );

Callbackdata

Um ponteiro para a estrutura de dados de retorno de chamada para a operação de E/S.

Contexto

Um ponteiro de informações de contexto que foi passado no parâmetro Context para FltCheckOplock.

Retornar valor

FltCheckOplock retorna um dos seguintes códigos de FLT_PREOP_CALLBACK_STATUS:

Código de retorno	Descrição
FLT_PREOP_COMPLETE	FltCheckOplock encontrou uma falha de alocação de pool ou uma chamada para a função FsRtlCheckOplock retornou um erro. FltCheckOplock definirá o código de erro no membro Status da estrutura IO_STATUS_BLOCK do membro IoStatus da estrutura de dados de retorno de chamada FLT_CALLBACK_DATA . O parâmetro CallbackData aponta para esse FLT_CALLBACK_DATA.
FLT_PREOP_PENDING	Uma interrupção de oplock foi iniciada, o que fez com que o Gerenciador de Filtros poste a operação de E/S em uma fila de trabalho. A operação de E/S é representada pelos dados de retorno de chamada para os quais o parâmetro CallbackData aponta.
FLT_PREOP_SUCCESS_WITH_CALLBACK	A operação de E/S foi executada imediatamente. Lembre-se de que, se essa operação foi uma operação de criação que especificou FILE_COMPLETE_IF_OPLOCKED no parâmetro create-options, pode realmente haver uma quebra de oplock em andamento, mesmo que a operação tenha sido executada imediatamente. Para determinar se essa é a situação, o chamador deve marcar o status no membro Status da estrutura IO_STATUS_BLOCK do membro IoStatus da estrutura de dados de retorno de chamada FLT_CALLBACK_DATA.

Comentários

Um driver de minifiltro chama FltCheckOplock para sincronizar uma operação de E/S baseada em IRP 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 quebra de oplock seja concluída, FltCheckOplock retornará FLT_PREOP_PENDING e chamará a rotina de retorno de chamada para a qual o parâmetro PrePostCallbackDataRoutine aponta.

Se um driver de minifiltro usar oplocks, ele deverá chamar FltCheckOplock de qualquer rotina de retorno de chamada de pré-operação (PFLT_PRE_OPERATION_CALLBACK) 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:

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

A operação de E/S deve ser uma operação de E/S baseada em IRP. Para determinar se uma determinada estrutura de dados de retorno de chamada representa uma operação de E/S baseada em IRP, use a macro FLT_IS_IRP_OPERATION .

Minifilters não devem chamar FltCheckOplock novamente dentro do retorno de chamada especificado em WaitCompletionRoutine. Isso poderá resultar em uma condição de deadlock se o pacote oplock chamar o retorno de chamada de conclusão antes que FltCheckOplock retorne.

Para obter informações detalhadas sobre bloqueios oportunistas, consulte a documentação do SDK do Microsoft Windows.