Função WaitForSingleObjectEx (synchapi.h)
Aguarda até que o objeto especificado esteja no estado sinalizado, uma rotina de conclusão de E/S ou APC (chamada de procedimento assíncrono) seja enfileirada para o thread ou o intervalo de tempo limite decorre.
Para aguardar vários objetos, use WaitForMultipleObjectsEx.
Sintaxe
DWORD WaitForSingleObjectEx(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parâmetros
[in] hHandle
Um identificador para o objeto . Para obter uma lista dos tipos de objeto cujos identificadores podem ser especificados, consulte a seção Comentários a seguir.
Se esse identificador estiver fechado enquanto a espera ainda estiver pendente, o comportamento da função será indefinido.
O identificador deve ter o direito de acesso SYNCHRONIZE . Para obter mais informações, consulte Direitos de acesso padrão.
[in] dwMilliseconds
O intervalo de tempo limite em milissegundos. Se um valor diferente de zero for especificado, a função aguardará até que o objeto seja sinalizado, uma rotina de conclusão de E/S ou APC seja enfileirada ou o intervalo se especifique. Se dwMilliseconds for zero, a função não entrará em um estado de espera se os critérios não forem atendidos; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando o objeto for sinalizado ou uma rotina de conclusão de E/S ou APC estiver na fila.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: o valor dwMilliseconds inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está adormecido.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: o valor dwMilliseconds não inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite não continua em contagem regressiva enquanto o computador está adormecido.
[in] bAlertable
Se esse parâmetro for TRUE e o thread estiver no estado de espera, a função retornará quando o sistema enfileirar uma rotina de conclusão de E/S ou APC e o thread executar a rotina ou a função. Caso contrário, a função não retornará e a rotina de conclusão ou a função APC não será executada.
Uma rotina de conclusão é enfileirada quando a função ReadFileEx ou WriteFileEx na qual ela foi especificada foi concluída. A função de espera retorna e a rotina de conclusão é chamada somente se bAlertable for TRUE e o thread de chamada for o thread que iniciou a operação de leitura ou gravação. Um APC é enfileirado quando você chama QueueUserAPC.
Retornar valor
Se a função for bem-sucedida, o valor retornado indicará o evento que causou o retorno da função. Pode ser um dos seguintes valores.
Valor/código retornado | Descrição |
---|---|
|
O objeto especificado é um objeto mutex que não foi liberado pelo thread que possuía o objeto mutex antes do término do thread proprietário. A propriedade do objeto mutex é concedida ao thread de chamada e o mutex é definido como não atribuído.
Se o mutex estava protegendo informações de estado persistente, você deve marcar-lo para consistência. |
|
A espera foi encerrada por uma ou mais APC (chamadas de procedimento assíncronas ) no modo de usuário enfileiradas para o thread. |
|
O estado do objeto especificado é sinalizado. |
|
O intervalo de tempo limite passou e o estado do objeto não está atribuído. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Comentários
A função WaitForSingleObjectEx determina se os critérios de espera foram atendidos. Se os critérios não tiverem sido atendidos, o thread de chamada entrará no estado de espera até que as condições dos critérios de espera tenham sido atendidas ou o intervalo de tempo limite se escorra.
A função modifica o estado de alguns tipos de objetos de sincronização. A modificação ocorre apenas para o objeto cujo estado sinalizado fez com que a função retornasse. Por exemplo, a contagem de um objeto de semáforo é reduzida em um.
A função WaitForSingleObjectEx pode aguardar os seguintes objetos:
- Notificação de alteração
- Entrada do console
- Evento
- Notificação de recursos de memória
- Mutex
- Processar
- Sinal
- Thread
- Temporizador de espera
Exemplos
Para obter um exemplo, consulte Servidor de pipe nomeado usando rotinas de conclusão.
Requisitos
Requisito | Valor |
---|---|
Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
Plataforma de Destino | Windows |
Cabeçalho | synchapi.h (inclua Windows.h no Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
Biblioteca | Kernel32.lib |
DLL | Kernel32.dll |