Função WaitForSingleObjectEx (synchapi.h)

  • Artigo

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
WAIT_ABANDONED
0x00000080L
 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.
WAIT_IO_COMPLETION
0x000000C0L
 A espera foi encerrada por uma ou mais APC (chamadas de procedimento assíncronas ) no modo de usuário enfileiradas para o thread.
WAIT_OBJECT_0
0x00000000L
 O estado do objeto especificado é sinalizado.
WAIT_TIMEOUT
0x00000102L
 O intervalo de tempo limite passou 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.

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
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 indiretamente janelas são DDE e a função CoInitialize . Portanto, se você tiver um thread que cria janelas, use MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, em vez de WaitForSingleObjectEx.

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

Confira também

Funções de sincronização

Funções de espera