Função GetMessageW (winuser.h)

Artigo
11/20/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.

Ao contrário 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

Tipo: 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 todas as mensagens na fila de mensagens do thread atual cujo valor de hwnd é NULL (consulte a estrutura de do MSG ). Portanto, se o 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 de 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 em 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 em 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).

Valor de retorno

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 um 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); 
    }
}

Observações

Um aplicativo normalmente usa o valor retornado para determinar se o loop de mensagem principal deve ser encerrado e encerrado.

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 o SendMessage, SendMessageCallback, SendMessageTimeoutou função 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)
mensagens WM_PAINT
mensagens WM_TIMER

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

GetMessage não remove mensagens WM_PAINT da fila. As mensagens permanecem na fila até serem processadas.

Se uma janela de nível superior parar de responder às 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 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	winuser.h (inclua Windows.h)
biblioteca	User32.lib
de DLL	User32.dll
conjunto de API	ext-ms-win-ntuser-message-l1-1-0 (introduzido no Windows 8)

Consulte também

Conceitual

IsChild

MSG

mensagens e filas de mensagens

PeekMessage

PostMessage

PostThreadMessage

de referência de

WaitMessage

Compartilhar via