Função FltCheckOplockEx (fltkernel.h)
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 de arquivo associada. Um driver de minifiltro define bits para especificar o comportamento de FltCheckOplockEx. O parâmetro Flags 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 marcar para uma chave de bloqueio oportunista na FILE_OBJECT associada à operação de E/S. Essas operações de E/S são representadas pelos dados de retorno de chamada para os quais o parâmetro CallbackData aponta. FltCheckOplockEx deverá 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 tenha sido configurado anteriormente por meio de uma chamada para a rotina 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 dessa 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 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
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.
[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.
Retornar valor
FltCheckOplockEx retorna um dos seguintes códigos de FLT_PREOP_CALLBACK_STATUS:
| Código de retorno | Descrição |
|---|---|
|
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 FLT_CALLBACK_DATA. |
|
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. |
|
Os dados de retorno de chamada para os quais o parâmetro CallbackData aponta não estavam pendentes e a operação de E/S foi executada imediatamente. Lembre-se de que, se o chamador especificou 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 marcar para STATUS_OPLOCK_BREAK_IN_PROGRESS 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 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 quebra de 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 .
Minifilters não devem chamar FltCheckOplockEx 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 FltCheckOplockEx retorne.
Para obter mais informações sobre bloqueios oportunistas, consulte a documentação do SDK do Microsoft Windows.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | A rotina FltCheckOplockEx está disponível a partir do Windows 7. |
| Plataforma de Destino | Universal |
| Cabeçalho | fltkernel.h (inclua Fltkernel.h) |
| Biblioteca | FltMgr.lib |
| IRQL | <= APC_LEVEL |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de