Função ZwWaitForSingleObject (ntifs.h)
A rotina de
Sintaxe
NTSYSAPI NTSTATUS ZwWaitForSingleObject(
[in] HANDLE Handle,
[in] BOOLEAN Alertable,
[in, optional] PLARGE_INTEGER Timeout
);
Parâmetros
[in] Handle
Um identificador para o objeto.
[in] Alertable
Um valor booliano que especifica se a espera é alertável.
[in, optional] Timeout
Um ponteiro opcional para um valor de tempo limite que especifica o tempo absoluto ou relativo em que a espera deve ser concluída. Um valor negativo especifica um intervalo relativo à hora atual. O valor deve ser expresso em unidades de 100 nanossegundos. 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.
Valor de retorno
ZwWaitForSingleObject pode retornar um dos seguintes códigos de status possíveis:
| Código de retorno | Descrição |
|---|---|
| STATUS_ACCESS_DENIED | O chamador não tinha os privilégios necessários para o evento especificado pelo parâmetro Handle. |
| STATUS_ALERTED | A espera foi anulada para entregar um alerta ao thread atual. |
| STATUS_INVALID_HANDLE | O parâmetro Handle fornecido era inválido. |
| STATUS_SUCCESS | O objeto especificado satisfizeva a espera. |
| STATUS_TIMEOUT | Ocorreu um tempo limite antes de o objeto ser definido como um estado sinalizado. Esse valor pode ser retornado quando o conjunto especificado de condições de espera não puder ser atendido imediatamente e o parâmetro Timeout for definido como zero. |
| STATUS_USER_APC | A espera foi anulada para entregar um APC de usuário ao thread atual. |
Observe que a macro NT_SUCCESS reconhece os valores de status STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT e STATUS_USER_APC como valores de "êxito".
Observações
ZwWaitForSingleObject aguarda até que o objeto especificado atinja um estado de Signaled. Um tempo limite opcional também pode ser especificado. ZwWaitForSingleObject examina o estado atual do objeto especificado para determinar se a espera pode ser atendida imediatamente. Nesse caso, as ações serão executadas. Caso contrário, o thread atual será colocado em um estado de espera e um novo thread será selecionado para execução no processador atual.
Se um parâmetro Timeout não for especificado, a espera não será atendida até que o objeto atinja um estado de Signaled. Se um parâmetro Timeout for especificado e o objeto não tiver atingido um estado de Signaled quando o tempo limite expirar, a espera será atendida automaticamente. Se um tempo limite explícito valor de zero for especificado, nenhuma espera ocorrerá se a espera não puder ser atendida imediatamente. Um Timeout valor zero permite o teste de um conjunto de condições de espera e para o desempenho condicional de quaisquer efeitos colaterais se a espera puder ser atendida imediatamente, como na aquisição de um mutex. A espera também pode ser especificada como alertável.
O parâmetro alertável especifica se o thread pode ser alertado e seu estado de espera consequentemente anulado. Se o valor desse parâmetro for FALSE, o thread não poderá ser alertado. A única exceção a essa regra é a de um thread de encerramento. Em determinadas circunstâncias, um thread de encerramento pode ser alertado enquanto ele está em processo de encerramento. Um thread é automaticamente tornado alertável, por exemplo, quando encerrado por um usuário com um CTRL+C.
Se o valor de alertávelfor TRUE e uma das seguintes condições estiver presente, o thread será alertado:
- Se a origem do alerta for uma rotina interna de modo kernel não documentada usada para alertar threads.
- A origem do alerta é um APC no modo de usuário.
No primeiro desses dois casos, a espera do thread é satisfeita com um status de conclusão de STATUS_ALERTED. No segundo caso, ele está satisfeito com um status de conclusão de STATUS_USER_APC.
O thread deve ser alertável para que um APC no modo de usuário seja entregue. Esse não é o caso para APCs no modo kernel. Um APC no modo kernel pode ser entregue e executado mesmo que o thread não seja alertado. Depois que a execução do APC for concluída, a espera do thread será retomada. Um thread nunca é alertado, nem sua espera é anulada pela entrega de um APC no modo kernel.
A entrega de APCs no modo kernel para um thread de espera não depende se o thread pode ser alertado. Se o APC no modo kernel for um APC especial no modo kernel, o APC será entregue desde que o IRQL seja menor que APC_LEVEL. Se o APC no modo kernel for um APC normal no modo kernel, o APC será entregue desde que as três condições a seguir mantenham: (1) o IRQL é menor que APC_LEVEL, (2) nenhum APC de kernel está em andamento e (3) o thread não está em uma seção crítica.
Se o identificador passado para ZwWaitForSingleObject se referir a um mutex, a entrega do APC será a mesma de todos os outros objetos dispatcher durante a espera. No entanto, uma vez zwWaitForSingleObject retorna com STATUS_SUCCESS e o thread realmente contém o mutex, apenas 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.
É especialmente importante verificar o valor retornado de
Todas as esperas de longo prazo poderão ser anuladas por um usuário se o parâmetro alertável
Para obter informações adicionais, consulte Os threads de espera recebem alertas e APCs?
Os chamadores de ZwWaitForSingleObject devem estar em execução no IRQL menor ou igual a DISPATCH_LEVEL. Normalmente, o chamador deve estar em execução no IRQL PASSIVE_LEVEL e em um contexto de thread nonarbitrary. Uma chamada durante a execução no IRQL DISPATCH_LEVEL será válida se e somente se o chamador especificar um parâmetro Timeout de zero. Ou seja, um driver não deve esperar por um intervalo diferente de zero no IRQL igual a DISPATCH_LEVEL.
Intervalos de tempo limite são medidos em relação ao relógio do sistema e a precisão da medida de tempo limite é limitada pela granularidade do relógio do sistema. Para obter mais informações, consulte de Precisão do Temporizador.
Se a chamada para a função ZwWaitForSingleObject
Para chamadas de drivers no modo kernel, as versões NtXxx e Zwxxx versões de uma rotina dos Serviços de Sistema Nativo do Windows podem se comportar de forma diferente na maneira como lidam e interpretam parâmetros de entrada. Para obter mais informações sobre a relação entre as versões NtXxx e ZwXxx de uma rotina, consulte Usando versões Nt e Zw das rotinas de serviços do sistema nativo.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP |
| da Plataforma de Destino |
Universal |
| cabeçalho | ntifs.h (inclua Ntifs.h, FltKernel.h) |
| biblioteca | NtosKrnl.lib |
| de DLL |
NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| regras de conformidade de DDI | HwStorPortProhibitedDIs(storport), SpNoWait(storport) |