Compartilhar via

Função PeekMessageA (winuser.h)

  • Artigo

Despacha mensagens não enviadas de entrada, verifica a fila de mensagens de thread para uma mensagem postada e recupera a mensagem (se houver alguma).

Sintaxe

BOOL PeekMessageA(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax,
  [in]           UINT  wRemoveMsg
);

Parâmetros

[out] lpMsg

Tipo: LPMSG

Um ponteiro para uma estrutura msg que recebe informações de mensagem.

[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, PeekMessage 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, PeekMessage recuperará apenas mensagens na fila de mensagens do thread atual cujo valor é NULL, ou seja, mensagens de thread, conforme postado por postMessage (quando o parâmetro hWnd é NULL) ou postThreadMessage.

[in] wMsgFilterMin

Tipo: UINT

O valor da primeira mensagem no intervalo de mensagens a ser examinada. Use WM_KEYFIRST (0x0100) para especificar a primeira mensagem de teclado ou WM_MOUSEFIRST (0x0200) para especificar a primeira mensagem do mouse.

Se wMsgFilterMin e wMsgFilterMax forem zero, PeekMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).

[in] wMsgFilterMax

Tipo: UINT

O valor da última mensagem no intervalo de mensagens a ser examinada. Use WM_KEYLAST para especificar a última mensagem de teclado ou WM_MOUSELAST para especificar a última mensagem do mouse.

Se wMsgFilterMin e wMsgFilterMax forem zero, PeekMessage retornará todas as mensagens disponíveis (ou seja, nenhuma filtragem de intervalo será executada).

[in] wRemoveMsg

Tipo: UINT

Especifica como as mensagens devem ser tratadas. Esse parâmetro pode ser um ou mais dos valores a seguir.

Valor Significado
PM_NOREMOVE
0x0000
 As mensagens não são removidas da fila após o processamento PeekMessage .
PM_REMOVE
0x0001
 As mensagens são removidas da fila após o processamento PeekMessage .
PM_NOYIELD
0x0002
 Impede que o sistema libere qualquer thread que esteja aguardando o chamador ficar ocioso (consulte WaitForInputIdle).

Combine esse valor com PM_NOREMOVE ou PM_REMOVE.
 

Por padrão, todos os tipos de mensagem são processados. Para especificar que apenas determinada mensagem deve ser processada, especifique um ou mais dos valores a seguir.

Valor Significado
PM_QS_INPUT
(QS_INPUT << 16)
 Processar mensagens de mouse e teclado.
PM_QS_PAINT
(QS_PAINT << 16)
 Processar mensagens de pintura.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) << 16)
 Processe todas as mensagens postadas, incluindo temporizadores e teclas de acesso.
PM_QS_SENDMESSAGE
(QS_SENDMESSAGE << 16)
 Processe todas as mensagens enviadas.

Valor de retorno

Tipo: BOOL

Se uma mensagem estiver disponível, o valor retornado não será zero.

Se nenhuma mensagem estiver disponível, o valor retornado será zero.

Observações

PeekMessage 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 PeekMessage sempre recupera mensagens WM_QUIT, independentemente dos valores especificados para wMsgFilterMin e wMsgFilterMax.

Durante essa chamada, as expedições do sistema (DispatchMessage) mensagens pendentes, ou seja, mensagens enviadas para janelas pertencentes ao thread de chamada usando oSendMessage, SendMessageCallback, SendMessageTimeoutou 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.

A função PeekMessage normalmente não remove mensagens WM_PAINT da fila. WM_PAINT mensagens permanecem na fila até serem processadas. No entanto, se uma mensagem WM_PAINT tiver uma região de atualização de NULL, PeekMessage a removerá da fila.

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 um aplicativo está sendo depurado, o sistema não gera 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 Examinando uma fila de mensagens.

Nota

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

GetMessage

IsChild

MSG

mensagens e filas de mensagens

outros recursos

de referência de

WaitForInputIdle

WaitMessage