Função GetMessage (winuser.h)

Artigo
03/13/2024

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

Para recuperar mensagens de entrada antes das mensagens postadas, use os parâmetros wMsgFilterMin e wMsgFilterMax .

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)