Função CoWaitForMultipleHandles (combaseapi.h)

  • Artigo

Aguarda que os identificadores especificados sejam sinalizados ou que um período de tempo limite especificado seja decorrido.

Sintaxe

HRESULT CoWaitForMultipleHandles(
  [in]  DWORD    dwFlags,
  [in]  DWORD    dwTimeout,
  [in]  ULONG    cHandles,
  [in]  LPHANDLE pHandles,
  [out] LPDWORD  lpdwindex
);

Parâmetros

[in] dwFlags

As opções de espera. Os valores possíveis são obtidos da enumeração COWAIT_FLAGS .

[in] dwTimeout

O período de tempo limite, em milissegundos.

[in] cHandles

O número de elementos na matriz pHandles .

[in] pHandles

Uma matriz de identificadores.

[out] lpdwindex

Um ponteiro para uma variável que, quando o status retornado é S_OK, recebe um valor que indica o evento que fez com que a função retornasse. Esse valor geralmente é o índice em pHandles para o identificador que foi sinalizado.

Se pHandles incluir um ou mais identificadores para objetos mutex, um valor entre WAIT_ABANDONED_0 e (WAIT_ABANDONED_0 + nCount - 1) indicará o índice em pHandles para o mutex que foi abandonado.

Se o sinalizador COWAIT_ALERTABLE for definido em dwFlags, um valor de WAIT_IO_COMPLETION indicará que a espera foi encerrada por uma ou mais APC (chamadas de procedimento assíncrono) no modo de usuário enfileiradas para o thread.

Consulte WaitForMultipleObjectsEx para obter mais informações.

Valor retornado

Essa função pode retornar os valores a seguir.

Nota O valor retornado de CoWaitForMultipleHandles poderá ser não determinístico se o sinalizador COWAIT_ALERTABLE estiver definido em dwFlags ou se pHandles incluir um ou mais identificadores para objetos mutex. A solução alternativa recomendada é chamar SetLastError(ERROR_SUCCESS) antes de CoWaitForMultipleHandles.
 
Código de retorno Descrição
S_OK
 O identificador ou os identificadores necessários foram sinalizados.
E_INVALIDARG
 pHandles era NULL, lpdwindex era NULL ou dwFlags não era um valor da enumeração COWAIT_FLAGS .
RPC_E_NO_SYNC
 O valor de pHandles era 0.
RPC_S_CALLPENDING
 O período de tempo limite decorrido antes do identificador ou identificador necessário ser sinalizado.

Comentários

Dependendo de quais sinalizadores são definidos no parâmetro dwFlags, CoWaitForMultipleHandles bloqueia o thread de chamada até que ocorra um dos seguintes eventos:

  • Um ou todos os identificadores são sinalizados. No caso de objetos mutex, essa condição também é atendida por um mutex que está sendo abandonado.
  • Uma APC (chamada de procedimento assíncrono) foi enfileirada para o thread de chamada com uma chamada para a função QueueUserAPC .
  • O período de tempo limite expira.
Se o chamador residir em um apartment de thread único, CoWaitForMultipleHandles entrará no loop modal COM e o loop de mensagem do thread continuará a expedir mensagens usando o filtro de mensagem do thread. Se nenhum filtro de mensagem for registrado para o thread, o processamento de mensagens COM padrão será usado.

Se o thread de chamada residir em um MTA (multithread apartment), CoWaitForMultipleHandles chamará a função WaitForMultipleObjectsEx .

Requisitos

   
Cliente mínimo com suporte Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho combaseapi.h (inclua Objbase.h)
Biblioteca Ole32.lib
DLL Ole32.dll

Confira também

COWAIT_FLAGS