Função MsgWaitForMultipleObjects (winuser.h)
Aguarda até que um ou todos os objetos especificados estejam no estado sinalizado ou o intervalo de tempo limite se especifique. Os objetos podem incluir objetos de evento de entrada, que você especifica usando o parâmetro dwWakeMask .
Para inserir um estado de espera alertável, use a função MsgWaitForMultipleObjectsEx .
Sintaxe
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
Parâmetros
[in] nCount
O número de identificadores de objeto na matriz apontada por pHandles. O número máximo de identificadores de objeto é MAXIMUM_WAIT_OBJECTS menos um. Se esse parâmetro tiver o valor zero, a função aguardará apenas um evento de entrada.
[in] pHandles
Uma matriz de identificadores de objeto. Para obter uma lista dos tipos de objeto cujos identificadores podem ser especificados, consulte a seção Comentários a seguir. A matriz pode conter identificadores de objetos de diferentes tipos. Ele pode não conter várias cópias do mesmo identificador.
Se um desses identificadores for fechado enquanto a espera ainda estiver pendente, o comportamento da função será indefinido.
Os identificadores devem ter o direito de acesso SYNCHRONIZE . Para obter mais informações, consulte Direitos de acesso padrão.
[in] fWaitAll
Se esse parâmetro for TRUE, a função retornará quando os estados de todos os objetos na matriz pHandles tiverem sido definidos como sinalizados e um evento de entrada tiver sido recebido. Se esse parâmetro for FALSE, a função retornará quando o estado de qualquer um dos objetos for definido como sinalizado ou um evento de entrada tiver sido recebido. Nesse caso, o valor retornado indica o objeto cujo estado fez com que a função retornasse.
[in] dwMilliseconds
O intervalo de tempo limite em milissegundos. Se um valor diferente de zero for especificado, a função aguardará até que os objetos especificados sejam sinalizados ou o intervalo se especifique. Se dwMilliseconds for zero, a função não entrará em um estado de espera se os objetos especificados não forem sinalizados; ele sempre retorna imediatamente. Se dwMilliseconds for INFINITE, a função retornará somente quando os objetos especificados forem sinalizados.
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 energia. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está dormindo.
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 baixa potência Estados. Por exemplo, o tempo limite não mantém a contagem regressiva enquanto o computador está dormindo.
[in] dwWakeMask
Os tipos de entrada para os quais um identificador de objeto de evento de entrada será adicionado à matriz de identificadores de objeto. Esse parâmetro pode ser qualquer combinação dos valores listados no parâmetro de sinalizadoresGetQueueStatus.
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. (Observe que WAIT_OBJECT_0 é definido como 0 e WAIT_ABANDONED_0 é definido como 0x00000080L.)
| Código/valor de retorno | Descrição |
|---|---|
|
Se bWaitAll for TRUE, um valor retornado dentro do intervalo especificado indicará que o estado de todos os objetos especificados será sinalizado. Se bWaitAll for FALSE, o valor retornado menos WAIT_OBJECT_0 indicará o índice de matriz pHandles do objeto que atendeu à espera. |
|
A nova entrada do tipo especificado no parâmetro dwWakeMask está disponível na fila de entrada do thread. Funções como PeekMessage, GetMessage e WaitMessage marcam mensagens na fila como mensagens antigas. Portanto, depois de chamar uma dessas funções, uma chamada subsequente para MsgWaitForMultipleObjects não retornará até que uma nova entrada do tipo especificado chegue.
Esse valor também é retornado após a ocorrência de um evento do sistema que requer a ação do thread, como ativação em primeiro plano. Portanto, MsgWaitForMultipleObjects pode retornar mesmo que nenhuma entrada apropriada esteja disponível e mesmo que dwWakeMask esteja definido como 0. Se isso ocorrer, chame GetMessage ou PeekMessage para processar o evento do sistema antes de tentar a chamada para MsgWaitForMultipleObjects novamente. |
|
Se bWaitAll for TRUE, um valor retornado dentro do intervalo especificado indicará que o estado de todos os objetos especificados é sinalizado e pelo menos um dos objetos é um objeto mutex abandonado. Se bWaitAll for FALSE, o valor retornado menos WAIT_ABANDONED_0 indicará o índice de matriz pHandles de um objeto mutex abandonado que atendeu à espera. 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 verificar se há consistência. |
|
O intervalo de tempo limite decorrido e as condições especificadas pelos parâmetros bWaitAll e dwWakeMask não foram atendidas. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Comentários
A função MsgWaitForMultipleObjects 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.
Quando bWaitAll for TRUE, a função não modificará os estados dos objetos especificados até que os estados de todos os objetos tenham sido definidos como sinalizados. Por exemplo, um mutex pode ser sinalizado, mas o thread não obtém a propriedade até que os estados dos outros objetos também tenham sido definidos como sinalizados. Enquanto isso, algum outro thread pode obter a propriedade do mutex, definindo assim seu estado como não atribuído.
Quando bWaitAll for TRUE, a espera da função será concluída somente quando os estados de todos os objetos tiverem sido definidos como sinalizados e um evento de entrada tiver sido recebido. Portanto, definir bWaitAll como TRUE impede que a entrada seja processada até que o estado de todos os objetos na matriz pHandles tenha sido definido como sinalizado. Por esse motivo, se você definir bWaitAll como TRUE, deverá usar um valor de tempo limite curto em dwMilliseconds. Se você tiver um thread que cria janelas aguardando todos os objetos na matriz pHandles , incluindo eventos de entrada especificados por dwWakeMask, sem intervalo de tempo limite, o sistema fará deadlock. Isso ocorre porque os threads que criam janelas devem processar mensagens. O DDE envia uma mensagem para todas as janelas do sistema. Portanto, se um thread criar janelas, não defina o parâmetro bWaitAll como TRUE em chamadas para MsgWaitForMultipleObjects feitas desse thread.
Quando bWaitAll é FALSE, essa função verifica os identificadores na matriz a partir do índice 0, até que um dos objetos seja sinalizado. Se vários objetos forem sinalizados, a função retornará o índice do primeiro identificador na matriz cujo objeto foi sinalizado.
MsgWaitForMultipleObjects não retornará se houver entrada não lida do tipo especificado na fila de mensagens depois que o thread tiver chamado uma função para verificar a fila. Isso ocorre porque funções como PeekMessage, GetMessage, GetQueueStatus e WaitMessage verificam a fila e alteram as informações de estado da fila para que a entrada não seja mais considerada nova. Uma chamada subsequente para MsgWaitForMultipleObjects não retornará até que uma nova entrada do tipo especificado chegue. A entrada não lida existente (recebida antes da última vez em que o thread verificou a fila) é ignorada.
A função modifica o estado de alguns tipos de objetos de sincronização. A modificação ocorre apenas para o objeto ou objetos cujo estado sinalizado fez com que a função retornasse. Por exemplo, a contagem de um objeto de semáforo é reduzida em um. Para obter mais informações, consulte a documentação dos objetos de sincronização individuais.
A função MsgWaitForMultipleObjects pode especificar identificadores de qualquer um dos seguintes tipos de objeto na matriz pHandles :
- Notificação de alteração
- Entrada do console
- Evento
- Notificação de recursos de memória
- Mutex
- Processar
- Sinal
- Thread
- Temporizador de espera
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winuser.h (inclua Windows.h) |
| Biblioteca | User32.lib |
| DLL | User32.dll |