Função PostThreadMessageW (winuser.h)

Artigo
05/20/2023

Posta uma mensagem na fila de mensagens do thread especificado. Ele retorna sem esperar que o thread processe a mensagem.

Sintaxe

BOOL PostThreadMessageW(
  [in] DWORD  idThread,
  [in] UINT   Msg,
  [in] WPARAM wParam,
  [in] LPARAM lParam
);

Parâmetros

[in] idThread

Tipo: DWORD

O identificador do thread no qual a mensagem deve ser postada.

A função falhará se o thread especificado não tiver uma fila de mensagens. O sistema cria a fila de mensagens de um thread quando o thread faz sua primeira chamada para uma das funções Usuário ou GDI. Para obter mais informações, consulte a seção Comentários.

A postagem de mensagens está sujeita à UIPI. O thread de um processo pode postar mensagens somente em filas de threads de mensagens postadas em processos de nível de integridade menor ou igual.

Esse thread deve ter o privilégio SE_TCB_NAME para postar uma mensagem em um thread que pertence a um processo com o mesmo LUID (identificador local exclusivo), mas está em uma área de trabalho diferente. Caso contrário, a função falhará e retornará ERROR_INVALID_THREAD_ID.

Esse thread deve pertencer à mesma área de trabalho que o thread de chamada ou a um processo com o mesmo LUID. Caso contrário, a função falhará e retornará ERROR_INVALID_THREAD_ID.

[in] Msg

Tipo: UINT

O tipo de mensagem a ser postada.

[in] wParam

Tipo: WPARAM

Obter informações adicionais específicas de mensagem.

[in] lParam

Tipo: LPARAM

Obter informações adicionais específicas de mensagem.

Retornar valor

Tipo: BOOL

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. GetLastError retornará ERROR_INVALID_THREAD_ID se idThread não for um identificador de thread válido ou se o thread especificado por idThread não tiver uma fila de mensagens. GetLastError retorna ERROR_NOT_ENOUGH_QUOTA quando o limite da mensagem é atingido.

Comentários

Quando uma mensagem é bloqueada pela UIPI, o último erro, recuperado com GetLastError, é definido como 5 (acesso negado).

O thread no qual a mensagem é postada deve ter criado uma fila de mensagens ou a chamada para PostThreadMessage falhará. Use o método a seguir para lidar com essa situação.

Crie um objeto de evento e, em seguida, crie o thread.
Use a função WaitForSingleObject para aguardar o evento ser definido como o estado sinalizado antes de chamar PostThreadMessage.
No thread no qual a mensagem será postada, chame PeekMessage conforme mostrado aqui para forçar o sistema a criar a fila de mensagens.
PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE)
Defina o evento para indicar que o thread está pronto para receber mensagens postadas.

O thread no qual a mensagem é postada recupera a mensagem chamando a função GetMessage ou PeekMessage . O membro hwnd da estrutura MSG retornada é NULL.

As mensagens postadas por PostThreadMessage não estão associadas a uma janela. Como regra geral, as mensagens que não estão associadas a uma janela não podem ser expedidas pela função DispatchMessage . Portanto, se o thread do destinatário estiver em um loop modal (conforme usado por MessageBox ou DialogBox), as mensagens serão perdidas. Para interceptar mensagens de thread em um loop modal, use um gancho específico do thread.

O sistema faz marshaling apenas para mensagens do sistema (aquelas no intervalo de 0 a (WM_USER-1)). Para enviar outras mensagens (essas >= WM_USER) para outro processo, você deve fazer marshaling personalizado.

Há um limite de 10.000 mensagens postadas por fila de mensagens. Esse limite deve ser suficientemente grande. Se o aplicativo exceder o limite, ele deverá ser reprojetado para evitar o consumo de tantos recursos do sistema. Para ajustar esse limite, modifique a chave do Registro a seguir.

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               Windows
                  USERPostMessageLimit

O valor mínimo aceitável é 4000.

Observação

O cabeçalho winuser.h define PostThreadMessage como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-message-l1-1-0 (introduzido no Windows 8)