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 no 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 apontado 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. 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 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 os objetos especificados sejam sinalizados, uma rotina de conclusão de E/S ou APC seja enfileirada ou o intervalo decorrido. 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 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.
[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 em sinalizadores GetQueueStatus parâmetro.
[in] dwFlags
O tipo de espera. Esse parâmetro pode ser um ou mais dos valores a seguir.
| Valor | Significado |
|---|---|
|
A função retorna quando qualquer um dos objetos é sinalizado. O valor retornado indica o objeto cujo estado causou o retorno da função. |
|
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 houver entrada 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 |
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. (Observe que WAIT_OBJECT_0 é definido como 0 e WAIT_ABANDONED_0 é definido como 0x00000080L.)
| Código/valor de retorno | 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 será sinalizado. Caso contrário, o valor retornado menos WAIT_OBJECT_0 indica o índice pHandles matriz do objeto que causou o retorno da função. |
|
A nova entrada do tipo especificado no parâmetro 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 pHandles matriz de um objeto mutex abandonado que causou o retorno da função. 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. |
|
A espera foi encerrada por um ou mais chamadas de procedimento assíncronas (APC) enfileiradas no thread. |
|
O intervalo de tempo limite decorrido, mas as condições especificadas pelo dwFlags e dwWakeMask parâmetros não foram atendidas. |
|
A função falhou. Para obter informações de erro estendidas, chame GetLastError. |
Observações
A função MsgWaitForMultipleObjectsEx
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 uma entrada não lida do tipo especificado na fila de mensagens depois que o thread tiver chamado uma função para verificar a fila, a menos que você use o sinalizador MWMO_INPUTAVAILABLE. Isso ocorre porque funções como PeekMessage, GetMessage, GetQueueStatuse WaitMessage verificar a fila e, em seguida, alterar 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 semáforo em um. Para obter mais informações, consulte a documentação dos objetos de sincronização individuais.
A função
- Alterar notificação
- Entrada do console
- Acontecimento
- Notificação de recurso de memória
- Mutex
- Processo
- Semáforo
- Fio
- Temporizador aguardável
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2003 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winuser.h (inclua Windows.h) |
| biblioteca | User32.lib |
| de DLL |
User32.dll |