Função GetMessage (winuser.h)
Recupera uma mensagem da fila de mensagens do thread de chamada. A função despacha mensagens enviadas de entrada até que uma mensagem postada esteja disponível para recuperação.
Funções GetMessage como PeekMessage, no entanto, GetMessage bloqueia até que uma mensagem seja postada antes de retornar.
Sintaxe
BOOL GetMessage(
[out] LPMSG lpMsg,
[in, optional] HWND hWnd,
[in] UINT wMsgFilterMin,
[in] UINT wMsgFilterMax
);
Parâmetros
[out] lpMsg
Tipo: LPMSG
Um ponteiro para uma estrutura MSG que recebe informações de mensagem da fila de mensagens do thread.
[in, optional] hWnd
Digite: HWND
Um identificador para a janela cujas mensagens devem ser recuperadas. A janela deve pertencer ao thread atual.
Se hWnd for NULL, GetMessage recuperará mensagens para qualquer janela que pertença ao thread atual e quaisquer mensagens na fila de mensagens do thread atual cujo valor hwnd seja NULL (consulte a estrutura MSG ). Portanto, se hWnd for NULL, as mensagens de janela e as mensagens de thread serão processadas.
Se hWnd for -1, GetMessage recuperará apenas mensagens na fila de mensagens do thread atual cujo valor hwnd é NULL, ou seja, mensagens de thread, conforme postado por PostMessage (quando o parâmetro hWnd é NULL) ou PostThreadMessage.
[in] wMsgFilterMin
Tipo: UINT
O valor inteiro do valor de mensagem mais baixo a ser recuperado. Use WM_KEYFIRST (0x0100) para especificar a primeira mensagem de teclado ou WM_MOUSEFIRST (0x0200) para especificar a primeira mensagem do mouse.
Use WM_INPUT aqui e no wMsgFilterMax para especificar apenas as mensagens WM_INPUT .
Se wMsgFilterMin e wMsgFilterMax forem zero, GetMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).
[in] wMsgFilterMax
Tipo: UINT
O valor inteiro do valor de mensagem mais alto a ser recuperado. Use WM_KEYLAST para especificar a última mensagem de teclado ou WM_MOUSELAST para especificar a última mensagem do mouse.
Use WM_INPUT aqui e no wMsgFilterMin para especificar apenas as mensagens WM_INPUT .
Se wMsgFilterMin e wMsgFilterMax forem zero, GetMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).
Retornar valor
Tipo: BOOL
Se a função recuperar uma mensagem diferente de WM_QUIT, o valor retornado não será zero.
Se a função recuperar a mensagem WM_QUIT , o valor retornado será zero.
Se houver um erro, o valor retornado será -1. Por exemplo, a função falhará se hWnd for um identificador de janela inválido ou lpMsg for um ponteiro inválido. Para obter informações de erro estendidas, chame GetLastError.
Como o valor retornado pode ser diferente de zero, zero ou -1, evite código como este:
while (GetMessage( lpMsg, hWnd, 0, 0)) ...
A possibilidade de um valor retornado -1 no caso de hWnd ser um parâmetro inválido (como fazer referência a uma janela que já foi destruída) significa que esse código pode levar a erros fatais do aplicativo. Em vez disso, use um código como este:
BOOL bRet;
while( (bRet = GetMessage( &msg, hWnd, 0, 0 )) != 0)
{
if (bRet == -1)
{
// handle the error and possibly exit
}
else
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
Comentários
Um aplicativo normalmente usa o valor retornado para determinar se deseja encerrar o loop de mensagem main e sair do programa.
A função GetMessage recupera mensagens associadas à janela identificada pelo parâmetro hWnd ou qualquer um de seus filhos, conforme especificado pela função IsChild , e dentro do intervalo de valores de mensagem fornecidos pelos parâmetros wMsgFilterMin e wMsgFilterMax . Observe que um aplicativo só pode usar a palavra baixa nos parâmetros wMsgFilterMin e wMsgFilterMax ; a palavra alta é reservada para o sistema.
Observe que GetMessage sempre recupera mensagens WM_QUIT , independentemente dos valores especificados para wMsgFilterMin e wMsgFilterMax.
Durante essa chamada, o sistema fornece mensagens pendentes, ou seja, mensagens enviadas para janelas pertencentes ao thread de chamada usando a função SendMessage, SendMessageCallback, SendMessageTimeout ou SendNotifyMessage . Em seguida, a primeira mensagem enfileirada que corresponde ao filtro especificado é recuperada. O sistema também pode processar eventos internos. Se nenhum filtro for especificado, as mensagens serão processadas na seguinte ordem:
- Mensagens enviadas
- Mensagens postadas
- Mensagens de entrada (hardware) e eventos internos do sistema
- Mensagens enviadas (novamente)
- WM_PAINT mensagens
- WM_TIMER mensagens
GetMessage não remove WM_PAINT mensagens da fila. As mensagens permanecem na fila até serem processadas.
Se uma janela de nível superior parar de responder a mensagens por mais de vários segundos, o sistema considerará que a janela não está respondendo e a substituirá por uma janela fantasma que tenha os mesmos atributos de ordem z, local, tamanho e visual. Isso permite que o usuário o mova, redimensione-o ou até mesmo feche o aplicativo. No entanto, essas são as únicas ações disponíveis porque o aplicativo realmente não está respondendo. Quando estiver no modo de depurador, o sistema não gerará uma janela fantasma.
Virtualização de DPI
Essa API não participa da virtualização de DPI. A saída está no modo da janela que a mensagem está direcionando. O thread de chamada não é levado em consideração.Exemplos
Para obter um exemplo, consulte Criando um loop de mensagem.
Requisitos
| Requisito | Valor |
|---|---|
| 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 em Windows 8) |
Confira também
Conceitual
Mensagens e filas de mensagens
Referência