Compartilhar via


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 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á dormindo.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: O dwMilliseconds valor 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
0
A função retorna quando qualquer um dos objetos é sinalizado. O valor retornado indica o objeto cujo estado causou o retorno da função.
MWMO_ALERTABLE
0x0002
A função também retornará se um APC tiver sido enfileirado no thread com QueueUserAPC enquanto o thread estiver no estado de espera.
MWMO_INPUTAVAILABLE
0x0004
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.
MWMO_WAITALL
0x0001
A função retorna quando todos os objetos na matriz pHandles são sinalizados e um evento de entrada é recebido, tudo ao mesmo tempo.

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
WAIT_OBJECT_0 para (WAIT_OBJECT_0 + nCount – 1)
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.
WAIT_OBJECT_0 + nCount
A nova entrada do tipo especificado no parâmetro dwWakeMask está disponível na fila de entrada do thread. Funções como PeekMessage, GetMessage, GetQueueStatuse WaitMessage marcar 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.

WAIT_ABANDONED_0 para (WAIT_ABANDONED_0 + nCount - 1)
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.

WAIT_IO_COMPLETION
0x000000C0L
A espera foi encerrada por um ou mais chamadas de procedimento assíncronas (APC) enfileiradas no thread.
WAIT_TIMEOUT
258L
O intervalo de tempo limite decorrido, mas as condições especificadas pelo dwFlags e dwWakeMask parâmetros não foram atendidas.
WAIT_FAILED
(DWORD)0xFFFFFFFF
A função falhou. Para obter informações de erro estendidas, chame GetLastError.

Observações

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 sejam atendidas ou o intervalo de tempo limite decorrido.

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 MsgWaitForMultipleObjectsEx pode especificar identificadores de qualquer um dos seguintes tipos de objeto na matriz pHandles :

  • 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

Consulte também

Funções de sincronização

Funções de espera