BOOL PeekMessage(lpMsg,hWnd,wMsgFilterMin,wMsgFilterMax,wRemoveMsg)
This function checks the application queue for a message and places the message (if any) in the data structure pointed to by the lpMsg parameter. Unlike the GetMessage function, the PeekMessage function does not wait for a message to be placed in the queue before returning. It does, however, yield control (if the PM_NOYIELD flag isn't set) and does not return control after the yield until Windows returns control to the application.
PeekMessage retrieves only messages associated with the window specified by the hWnd parameter, or any of its children as specified by the IsChild function, and within the range of message values given by the wMsgFilterMin and wMsgFilterMax parameters. If hWnd is NULL, PeekMessage retrieves messages for any window that belongs to the application making the call. (The PeekMessage function does not retrieve messages for windows that belong to other applications.) If hWnd is –1, PeekMessage returns only messages with a hWnd of NULL as posted by the PostAppMessage function. If wMsgFilterMin and wMsgFilterMax are both zero, PeekMessage returns all available messages (no range filtering is performed).
The WM_KEYFIRST and WM_KEYLAST flags can be used as filter values to retrieve all key messages; the WM_MOUSEFIRST and WM_MOUSELAST flags can be used to retrieve all mouse messages.
| Parameter | Type/Description |
| lpMsg | LPMSG Points to an MSG data structure that contains message information from the Windows application queue. | |
| hWnd | HWND Identifies the window whose messages are to be examined. | |
| wMsgFilterMin | WORD Specifies the value of the lowest message position to be examined. | |
| wMsgFilterMax | WORD Specifies the value of the highest message position to be examined. | |
| wRemoveMsg | WORD Specifies a combination of the flags described in the following list. PM_NOYIELD can be combined with either PM_NOREMOVE or PM_REMOVE: | |
| Parameter | Type/Description |
| Value | Meaning | |
| PM_NOREMOVE | Messages are not removed from the queue after processing by PeekMessage. | |
| PM_NOYIELD | Prevents the current task from halting and yielding system resources to another task. | |
| PM_REMOVE | Messages are removed from the queue after processing by PeekMessage. |
The return value specifies whether or not a message is found. It is nonzero if a message is available. Otherwise, it is zero.
PeekMessage does not remove WM_PAINT messages from the queue. The messages remain in the queue until processed. The GetMessage, PeekMessage, and WaitMessage functions yield control to other applications. These calls are the only way to let other applications run. If your application does not call any of these functions for long periods of time, other applications cannot run.
When GetMessage, PeekMessage, and WaitMessage yield control to other applications, the stack and data segments of the application calling the function may move in memory to accommodate the changing memory requirements of other applications.
If the application has stored long pointers to objects in the data or stack segment (global or local variables), and if they are unlocked, these pointers can become invalid after a call to GetMessage, PeekMessage, or WaitMessage. The lpMsg parameter of the called function remains valid in any case.