Função FltCancellableWaitForSingleObject (fltkernel.h)

Artigo
08/07/2023

A rotina FltCancellableWaitForSingleObject executa uma operação de espera cancelável (uma espera que pode ser encerrada) em um objeto dispatcher.

Sintaxe

NTSTATUS FLTAPI FltCancellableWaitForSingleObject(
  [in]           PVOID              Object,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PFLT_CALLBACK_DATA CallbackData
);

Parâmetros

[in] Object

Um ponteiro para um objeto dispatcher inicializado (evento, mutex, semáforo, thread ou temporizador) para o qual o chamador fornece o armazenamento.

[in, optional] Timeout

Um ponteiro para um valor de tempo limite opcional. Esse parâmetro especifica o tempo absoluto ou relativo, em 100 unidades nanossegundos, quando a espera deve ser concluída.

Se Timeout apontar para um valor zero (ou seja, *Timeout == 0), a rotina retornará sem esperar. Se o chamador fornecer um ponteiro NULL (ou seja, Timeout == NULL), a rotina aguardará indefinidamente até que o objeto seja definido como o estado sinalizado.

Um valor de Tempo limite positivo especifica um tempo absoluto, em relação a 1º de janeiro de 1601. Um valor de Tempo limite negativo especifica um intervalo relativo à hora atual. Os tempos de expiração absolutos acompanham as alterações na hora do sistema. Os tempos relativos de expiração não são afetados pelas alterações de tempo do sistema.

Se Timeout for especificado, a espera será atendida automaticamente se o objeto não estiver definido como o estado sinalizado quando o intervalo especificado expirar.

Um valor de tempo limite zero (ou seja, *Timeout == 0) permite testar um conjunto de condições de espera e executar condicionalmente quaisquer ações adicionais se a espera puder ser atendida imediatamente, como na aquisição de um mutex.

[in, optional] CallbackData

Um ponteiro para a estrutura FLT_CALLBACK_DATA que representa a operação de E/S emitida pelo usuário e que pode ser cancelada pelo usuário. O chamador deve garantir que a operação de E/S permanecerá válida durante essa rotina e que a E/S não deve ter um conjunto de rotina de cancelamento (por exemplo, uma função FltSetCancelCompletion não deve ter sido chamada na operação de E/S). Observe que o chamador deve manter o CallbackData; ele não pode ser passado para um driver de nível inferior.

Retornar valor

FltCancellableWaitForSingleObject pode retornar um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	O objeto dispatcher especificado pelo parâmetro Object foi definido como o estado sinalizado.
STATUS_TIMEOUT	Ocorreu um tempo limite antes de o objeto ser definido como um estado sinalizado. Esse valor também pode ser retornado quando a condição de espera especificada não pode ser atendida imediatamente e Timeout é definido como zero.
STATUS_ABANDONED_WAIT_0	O chamador tentou esperar por um mutex que foi abandonado.
STATUS_CANCELLED	A espera foi interrompida por uma solicitação de cancelamento pendente na operação de E/S. Observe que esse valor será retornado somente se CallbackData corresponder a uma operação baseada em IRP for passada para FltCancellableWaitForSingleObject e a E/S tiver sido cancelada por uma rotina como FltCancelIo.
STATUS_THREAD_IS_TERMINATING	A espera foi interrompida porque o aplicativo ou o usuário encerrou o thread.

O valor retornado indica apenas o status da espera.

Observe que a macro NT_SUCCESS retorna FALSE ("failure") para os valores STATUS_CANCELLED e STATUS_THREAD_IS_TERMINATING status e TRUE ("success") para todos os outros valores de status.

Comentários

A rotina FltCancellableWaitForSingleObject executa uma operação de espera cancelável em um objeto dispatcher. Se o usuário ou o aplicativo encerrar o thread ou se uma E/S associada ao thread tiver sido cancelada por uma rotina como FltCancelIo, a espera será cancelada.

A rotina foi projetada para dar suporte às Diretrizes de Conclusão/Cancelamento de E/S. O objetivo dessas diretrizes é permitir que os usuários encerrem rapidamente os aplicativos. Isso, por sua vez, requer que os aplicativos tenham a capacidade de encerrar rapidamente threads que estão executando E/S e quaisquer operações de E/S atuais. Essa rotina fornece uma maneira de os threads de usuário bloquearem (ou seja, aguardarem) no kernel para conclusão de E/S, objetos dispatcher ou variáveis de sincronização de uma maneira que permita que a espera seja prontamente cancelada. Essa rotina também permite que a espera do thread seja encerrada se o thread for encerrado por um usuário ou um aplicativo.

Por exemplo, um redirecionador pode precisar criar uma operação de E/S secundária para processar uma E/S no modo de usuário e aguardar a conclusão da solicitação secundária de forma síncrona. Uma maneira de fazer isso é configurar um evento que será sinalizado pela rotina de conclusão da operação de E/S secundária e aguardar o evento ser sinalizado. Em seguida, para executar uma operação de espera cancelável, FltCancellableWaitForSingleObject é chamado passando o evento associado à operação de E/S secundária e à operação de E/S original do modo de usuário. A espera do thread para que o evento seja sinalizado será cancelada se ocorrer um evento de encerramento pendente ou se a operação de E/S do modo de usuário original for cancelada.

Observe que encerrar a espera não cancela automaticamente nenhuma operação de E/S emitida pelo chamador , que deve ser tratada separadamente pelo chamador.

Uma consideração especial se aplica quando o parâmetro Object passado para FltCancellableWaitForSingleObject é um mutex. Se o objeto dispatcher que é aguardado for um mutex, a entrega do APC será a mesma que para todos os outros objetos dispatcher durante a espera. No entanto, uma vez que FltCancellableWaitForSingleObject retorna com STATUS_SUCCESS e o thread realmente contém o mutex, somente APCs especiais no modo kernel são entregues. A entrega de todas as outras APCs, no modo kernel e no modo de usuário, está desabilitada. Essa restrição na entrega de APCs persiste até que o mutex seja liberado.

Um mutex pode ser adquirido recursivamente apenas em tempos MINLONG. Se esse limite for excedido, a rotina gerará uma exceção STATUS_MUTANT_LIMIT_EXCEEDED.

FltCancellableWaitForSingleObject deve ser chamado em IRQL PASSIVE_LEVEL se o parâmetro CallbackData representar um IRP do gerenciador de filtros válido. Caso contrário, a rotina pode ser chamada em IRQL menor ou igual a APC_LEVEL. ApCs de kernel normais podem ser desabilitadas pelo chamador, se necessário, chamando as rotinas KeEnterCriticalRegion ou FsRtlEnterFileSystem . No entanto, APCs de kernel especiais não devem ser desabilitadas.

A rotina FltCancellableWaitForSingleObject será declarada em builds de depuração se CallbackData representar uma operação IRP do Gerenciador de Filtros, mas o IRP na estrutura CallbackData for NULL.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h, Ntifs.h)
Biblioteca	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	Consulte a seção Observações.