Compartilhar via

Função FltCheckOplockEx (fltkernel.h)

  • Artigo

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

Sintaxe

FLT_PREOP_CALLBACK_STATUS FLTAPI FltCheckOplockEx(
  [in]           POPLOCK                                 Oplock,
  [in]           PFLT_CALLBACK_DATA                      CallbackData,
  [in]           ULONG                                   Flags,
  [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 os dados de retorno de chamada FLT_CALLBACK_DATAestrutura para a operação de E/S.

[in] Flags

Uma máscara de bits para a operação de E/S do arquivo associado. Um driver de minifiltro define bits para especificar o comportamento de FltCheckOplockEx. O parâmetro sinalizadores de tem as seguintes opções:

OPLOCK_FLAG_COMPLETE_IF_OPLOCKED (0x00000001)

Permite 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)

Especifica que FltCheckOplockEx só deve verificar se há uma chave de bloqueio oportunista no FILE_OBJECT associado à operação de E/S. Essas operações de E/S são representadas pelos dados de retorno de chamada aos quais o parâmetro CallbackData aponta. FltCheckOplockEx deve adicionar a chave se uma for fornecida na operação de E/S. Nenhum outro processamento oplock ocorre; ou seja, nenhuma quebra de bloqueio oportunista ocorrerá.

OPLOCK_FLAG_BACK_OUT_ATOMIC_OPLOCK (0x00000004)

Especifica que FsRtlCheckOplockEx deve reverter qualquer estado que foi configurado anteriormente por meio de uma chamada para a rotina de FltOplockFsctrl. FltOplockFsctrl é chamado quando uma solicitação de IRP_MJ_CREATE é processada. Essa solicitação IRP_MJ_CREATE 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.

OPLOCK_FLAG_IGNORE_OPLOCK_KEYS (0x00000008)

Permite que todas as quebras de bloqueio oportunistas prossigam independentemente da chave de bloqueio oportunista.

[in, optional] Context

Um ponteiro para informações de contexto definidas pelo chamador a serem passadas para as rotinas de retorno de chamada que WaitCompletionRoutine e PrePostCallbackDataRoutine apontar para. 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 interrupção 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

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

Observação que, quando o WaitCompleteRoutine for chamado, a subestrutura do IoStatus poderá ser preenchida com um status de falha (por exemplo, STATUS_CANCELLED). Você deve inspecionar esse status e reagir adequadamente.

Contexto

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

[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 FltCheckOplockEx .

Valor de retorno

FltCheckOplockEx retorna um dos seguintes códigos de FLT_PREOP_CALLBACK_STATUS:

Código de retorno Descrição
FLT_PREOP_COMPLETE
 fltCheckOplockEx encontrou uma falha de alocação de pool ou uma chamada para a função FsRtlCheckOplockEx retornou um erro. FltCheckOplockEx define 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 essa estrutura de FLT_CALLBACK_DATA.
FLT_PREOP_PENDING
 Uma interrupção de oplock foi iniciada, o que fez com que o Gerenciador de Filtros postava a operação de E/S em uma fila de trabalho. A operação de E/S é representada pelos dados de retorno de chamada aos quais o parâmetro CallbackData aponta.
FLT_PREOP_SUCCESS_WITH_CALLBACK
 Os dados de retorno de chamada aos quais o parâmetro CallbackData não estavam pendentes e a operação de E/S foi executada imediatamente. Lembre-se de que, se o chamador especificado OPLOCK_FLAG_COMPLETE_IF_OPLOCKED no parâmetro Flags, uma quebra de oplock poderá realmente estar em andamento, mesmo que a operação de E/S não esteja pendente. Para determinar se essa é a situação, o chamador deve verificar se há STATUS_OPLOCK_BREAK_IN_PROGRESS no Status membro da estrutura IO_STATUS_BLOCK do membro do IoStatus da estrutura de dados de retorno de chamada FLT_CALLBACK_DATA.

Observações

Um driver de minifiltro chama FltCheckOplockEx 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 interrupção do oplock seja concluída, FltCheckOplockEx 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 fltCheckOplockEx 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.

Os minifiltros não devem chamar fltCheckOplockEx novamente dentro do retorno de chamada especificado noWaitCompletionRoutine . Isso poderá resultar em uma condição de deadlock se o pacote oplock chamar o retorno de chamada de conclusão antes de FltCheckOplockEx retornar.

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

Requisitos

Requisito Valor
de cliente com suporte mínimo A rotina FltCheckOplockEx está disponível a partir do Windows 7.
da Plataforma de Destino Universal
cabeçalho fltkernel.h (inclua Fltkernel.h)
biblioteca FltMgr.lib
IRQL <= APC_LEVEL

Consulte também

FLT_CALLBACK_DATA

FLT_IS_IRP_OPERATION

FltInitializeOplock

FltOplockFsctrl

FsRtlCheckOplockEx

IO_STATUS_BLOCK

PFLT_PRE_OPERATION_CALLBACK