Função GetMessageW (winuser.h)

Artigo
06/08/2023

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.

Ao contrário de GetMessage, a função PeekMessage não aguarda que uma mensagem seja postada antes de retornar.

Sintaxe

BOOL GetMessageW(
  [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 será diferente de 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 se referir 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 deve terminar 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 entrega 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 visuais, localização, tamanho e ordem z. 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 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.

Observação

O cabeçalho winuser.h define GetMessage 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

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 no Windows 8)