Função MsgWaitForMultipleObjectsEx (winuser.h)
Aguarda até que um ou todos os objetos especificados estejam 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 decorrido. A matriz de objetos pode incluir objetos de evento de entrada, que você especifica usando o parâmetro dwWakeMask .
Sintaxe
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
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 você pode especificar, consulte a seção Comentários mais adiante neste tópico. A matriz pode conter identificadores para vários tipos de objetos. 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] 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, 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 os objetos especificados forem sinalizados 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] 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.
[in] dwFlags
O tipo de espera. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
A função retorna quando qualquer um dos objetos é sinalizado. O valor retornado indica o objeto cujo estado fez com que a função retornasse. |
|
A função também retornará se um APC tiver sido enfileirado no thread com QueueUserAPC enquanto o thread estiver no estado de espera. |
|
A função retornará se a entrada existir para a fila, mesmo que a entrada tenha sido vista (mas não removida) usando uma chamada para outra função, como PeekMessage. |
|
A função retorna quando todos os objetos na matriz pHandles são sinalizados e um evento de entrada foi recebido, tudo ao mesmo tempo. |
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.)
| Valor/código retornado | Descrição |
|---|---|
|
Se o sinalizador MWMO_WAITALL for usado, um valor retornado dentro do intervalo especificado indicará que o estado de todos os objetos especificados é sinalizado. Caso contrário, o valor retornado menos WAIT_OBJECT_0 indica o índice de matriz pHandles do objeto que fez com que a função retornasse. |
|
A nova entrada do tipo especificado no parâmetro dwWakeMask está disponível na fila de entrada do thread. Funções como PeekMessage, GetMessage, GetQueueStatus e WaitMessage marcam mensagens na fila como mensagens antigas. Portanto, depois de chamar uma dessas funções, uma chamada subsequente para MsgWaitForMultipleObjectsEx 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, MsgWaitForMultipleObjectsEx 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 MsgWaitForMultipleObjectsEx novamente. |
|
Se o sinalizador MWMO_WAITALL for usado, 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. Caso contrário, o valor retornado menos WAIT_ABANDONED_0 indica o índice de matriz pHandles de um objeto mutex abandonado que fez com que a função retornasse. 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 intervalo de tempo limite expirou, mas as condições especificadas pelos parâmetros dwFlags e dwWakeMask não foram atendidas. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Comentários
A função MsgWaitForMultipleObjectsEx determina se as condições especificadas por dwWakeMask e dwFlags foram atendidas . Se as condições não tiverem sido atendidas, 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 dwFlags é zero, essa função verifica os identificadores na matriz para começar com o í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.
MsgWaitForMultipleObjectsEx 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 marcar fila, a menos que você use o sinalizador MWMO_INPUTAVAILABLE. Isso ocorre porque funções como PeekMessage, GetMessage, GetQueueStatus e WaitMessage marcar fila e alteram as informações de estado da fila para que a entrada não seja mais considerada nova. Uma chamada subsequente para MsgWaitForMultipleObjectsEx não retornará até que uma nova entrada do tipo especificado chegue, a menos que você use o sinalizador MWMO_INPUTAVAILABLE . Se esse sinalizador não for usado, a entrada não lida existente (recebida antes da última vez em que o thread verificou a fila) será 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, o sistema diminui a contagem de um objeto de semáforo em um. Para obter mais informações, consulte a documentação dos objetos de sincronização individuais.
A função MsgWaitForMultipleObjectsEx 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
| Requisito | Valor |
|---|---|
| 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 |
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de