Função MsgWaitForMultipleObjects (winuser.h)

Aguarda até que um ou todos os objetos especificados estejam no estado sinalizado ou o intervalo de tempo limite decorrido. 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 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 podem ser especificados, consulte a seção Comentários a seguir. A matriz pode conter identificadores de objetos de diferentes tipos. 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] 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 causou o retorno da funçã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 ou o intervalo decorrido. 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 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.

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.)

Observações

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

Quando bWaitAll é verdadeiro, a função não modifica 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 é VERDADEIRO, a espera da função é concluída somente quando os estados de todos os objetos foram definidos como sinalizados e um evento de entrada foi recebido. Portanto, a configuração bWaitAll para verdadeiro 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 para 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 será 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 para TRUE em chamadas para msgWaitForMultipleObjects feitas desse thread.

Quando bWaitAll é FALSE, 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.

MsgWaitForMultipleObjects 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. 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 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 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 :

• Alterar notificação
• Entrada do console
• Acontecimento
• Notificação de recurso de memória
• Mutex
• Processo
• Semáforo
• Fio
• Temporizador aguardável

Requisitos

Consulte também

MsgWaitForMultipleObjectsEx

Funções de sincronização

Funções de espera