PeekMessage Function

The PeekMessage function checks to see whether a message, placed in the message queue by a posted thread or the thread, is available. If a message is available, PeekMessage copies it into the structure pointed to by lpMsg and returns a nonzero value.

If no message is available, PeekMessage returns zero. PeekMessage never waits for a message to come into the queue.

Syntax

BOOL PeekMessage(
  LPMSG lpMsg,
  HWND  hWnd,
  UINT  wMsgFilterMin,
  UINT  wMsgFilterMax,
  UINT  wRemoveMsg
);

Parameters

Return Value

If a message is available, the return value is nonzero. Otherwise, the return value is zero.

Remarks

The PeekMessage function is typically used in the main message loop of an application.

If hWnd is NULL, PeekMessage retrieves messages for any window that belongs to the calling thread. This includes messages associated with child windows, but not messages from other threads.

The wMsgFilterMin and wMsgFilterMax parameters can be used to specify a range of messages to retrieve. If both are zero, all messages are retrieved.

Example

MSG msg;
BOOL bRet;

// Standard message loop
while( (bRet = PeekMessage( &msg, NULL, 0, 0, PM_REMOVE )) != 0 )
{
    if (bRet == -1) // Handle error
    {
        // Error handling code
        break;
    }

    // If it's a quit message, exit the loop
    if(msg.message == WM_QUIT)
    {
        PostQuitMessage(msg.wParam);
        break;
    }

    // Translate message
    TranslateMessage(&msg);

    // Dispatch message
    DispatchMessage(&msg);
}

// Process remaining messages in the queue if any
while(PeekMessage(&msg, NULL, 0, 0, PM_REMOVE)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);
}

Requirements

See Also

• MSG
• GetMessage
• TranslateMessage
• DispatchMessage
• PostQuitMessage