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
WAIT_ABANDONED
0x00000080L
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.

WAIT_OBJECT_0
0x00000000L
O estado do objeto especificado é sinalizado.
WAIT_TIMEOUT
0x00000102L
O intervalo de tempo limite decorrido e o estado do objeto não está atribuído.
WAIT_FAILED
(DWORD)0xFFFFFFFF
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
Tenha cuidado ao chamar as funções de espera e o código que cria janelas direta ou indiretamente. Se um thread criar janelas, ele deverá processar mensagens. As transmissões de mensagens são enviadas para todas as janelas do sistema. Um thread que usa uma função de espera sem intervalo de tempo limite pode fazer com que o sistema fique em deadlock. Dois exemplos de código que criam janelas indiretamente são DDE e a função CoInitialize. Portanto, se você tiver um thread que cria janelas, use MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, em vez de WaitForSingleObject.

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

Consulte também

Funções de sincronização

Funções de espera