Função WaitForSingleObject (synchapi.h)
Aguarda até que o objeto especificado esteja no estado sinalizado ou o intervalo de tempo limite decorrido.
Para inserir um estado de espera alertável, use a função WaitForSingleObjectEx. Para aguardar vários objetos, use WaitForMultipleObjects.
Sintaxe
DWORD WaitForSingleObject(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds
);
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 acesso SYNCHRONIZE direito. Para obter mais informações, consulte Standard Access Rights.
[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 ou o intervalo decorrido. Se dwMilliseconds for zero, a função não entrará em um estado de espera se o objeto não for sinalizado; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando o objeto for sinalizado.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: O dwMilliseconds valor inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está dormindo.
Windows 8 e mais recente, Windows Server 2012 e mais recente: o valor dwMilliseconds não inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite não mantém a contagem regressiva enquanto o computador está dormindo.
Valor de retorno
Se a função for bem-sucedida, o valor retornado indicará o evento que causou o retorno da função. Pode ser um dos valores a seguir.
| Código/valor de retorno | Descrição |
|---|---|
|
O objeto especificado é um objeto mutex que não foi liberado pelo thread que possuía o objeto mutex antes do thread proprietário ser encerrado. A propriedade do objeto mutex é concedida ao thread de chamada e o estado mutex é definido como não atribuído.
Se o mutex estava protegendo informações de estado persistente, você deve verificar se há consistência. |
|
O estado do objeto especificado é sinalizado. |
|
O intervalo de tempo limite decorrido e o estado do objeto não está atribuído. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Observações
A função WaitForSingleObject verifica o estado atual do objeto especificado. Se o estado do objeto não for atribuído, o thread de chamada entrará no estado de espera até que o objeto seja sinalizado ou o intervalo de tempo limite decorrido.
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 semáforo é reduzida em um.
A função WaitForSingleObject pode aguardar os seguintes objetos:
- Alterar notificação
- Entrada do console
- Acontecimento
- Notificação de recurso de memória
- Mutex
- Processo
- Semáforo
- Fio
- Temporizador aguardável
Exemplos
Para obter um exemplo, consulte Usando objetos Mutex.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da 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 |
| de DLL |
Kernel32.dll |