Função CoSetMessageDispatcher (messagedispatcherapi.h)

Registra ou cancela o registro do dispatcher de mensagens por thread que deve ser invocado quando há mensagens de janela disponíveis para expedição em APIs de espera COM em um thread ASTA. Essa função geralmente é chamada pelo CoreWindow, mas em determinadas circunstâncias outros componentes que precisam especializar como as mensagens são enviadas em um thread ASTA também podem chamar essa função.

Sintaxe

void CoSetMessageDispatcher(
  [in, optional] PMessageDispatcher pMessageDispatcher
);

Parâmetros

[in, optional] pMessageDispatcher

Se não for nulo, o objeto dispatcher de mensagem será registrado. Esse objeto também deve implementar IWeakReferenceSource. Se for nulo, cancelará o registro do dispatcher de mensagens atual.

Valor retornado

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

Essa função tem suporte apenas em threads ASTA. Uma tentativa de definir o dispatcher de mensagens em um thread não ASTA falha silenciosamente sem efeitos colaterais.

Uma tentativa de definir um objeto que não implementa IWeakReferenceSource falha silenciosamente sem efeitos colaterais.

Uma chamada para essa função com um parâmetro pMessageDispatcher válido e não nulo registra esse objeto para receber um retorno de chamada PumpMessages sempre que houver mensagens de janela disponíveis para expedição com APIs de espera COM nesse thread ASTA. Uma referência Windows Runtime fraca a esse objeto é mantida e o objeto recebe retornos de chamada, até que o registro seja substituído ou o ASTA não inicializado. Cada chamada para essa função substitui o dispatcher de mensagens registrado anteriormente, se houver.

Não há como marcar se um dispatcher de mensagens estiver registrado em um thread ASTA ou recuperar um dispatcher de mensagens registrado anteriormente. Essa função só deve ser chamada em circunstâncias em que se sabe que isso não colidirá com outro registro, especificamente:

• Nos threads de interface do usuário do aplicativo da Windows Store, essa função é chamada pelo CoreWindow para registrar seu dispatcher. Nenhum outro componente deve chamar essa função nesses threads.
• As estruturas de interface do usuário podem dar suporte a um modo de criação, no qual os aplicativos são executados no ambiente da área de trabalho e, portanto, não têm um CoreWindow em seus threads de interface do usuário. Em vez do suporte do CoreWindow, essas estruturas de interface do usuário podem registrar um dispatcher de mensagens em threads de interface do usuário para lidar com o processamento especial de mensagens de janela geralmente manipulado pelo CoreWindow (como aceleradores). Não será necessário chamar essa função se a estrutura da interface do usuário não tiver necessidade dessa funcionalidade.
• Os navegadores IAppVisibility não estão restritos às APIs de aplicativo da Windows Store e, portanto, podem ter seu próprio processamento de mensagem de janela personalizado usando APIs user32. No entanto, esses aplicativos ainda têm threads de interface do usuário do ASTA, conforme fornecido pelo objeto de aplicativo, e podem registrar um dispatcher de mensagens para lidar com esse processamento especial. Não é necessário chamar essa função se o navegador não tiver necessidade dessa funcionalidade.

O caso dos navegadores IAppVisibility requer cuidado para evitar que o CoreWindow substitua o dispatcher de mensagens do navegador. Supõe-se que o navegador não tenha necessidade do dispatcher do CoreWindow. O navegador deve chamar CoSetMessageDispatcher não antes de IViewProvider::Initialize ou, no caso de exibições que implementam IInitializeWithWindowFactory, não antes de ter criado uma janela no thread.

Requisitos

Plataforma de Destino	Windows
Cabeçalho	messagedispatcherapi.h

Confira também

IAppVisibility