GetMessage Function
The GetMessage function retrieves messages from the calling thread's message queue and places the message in the specified structure. This is a core function for handling Windows messages.
BOOL GetMessage(
_Out_ LPMSG lpMsg,
_In_opt_ HWND hWnd,
_In_ UINT wMsgFilterMin,
_In_ UINT wMsgFilterMax
);
Parameters
| Parameter | Type | Description |
|---|---|---|
lpMsg |
LPMSG |
A pointer to a MSG structure that receives message information. |
hWnd |
HWND |
A handle to the window whose messages are to be retrieved. If this parameter is NULL, this function retrieves messages for any window that is associated with the calling thread. If this parameter is (HWND) -1, this function retrieves messages for any message in the queue whose hwnd member is not NULL. |
wMsgFilterMin |
UINT |
The minimum value of messages to be retrieved. |
wMsgFilterMax |
UINT |
The maximum value of messages to be retrieved. |
Return Value
Nonzero (TRUE) if a message is retrieved.
Zero (FALSE) if no message is available and either hWnd is NULL, wMsgFilterMin and wMsgFilterMax are both 0, and the thread is exiting.
-1 if an error occurs.
Remarks
The GetMessage function retrieves messages from the queue of the calling thread. If the message queue is empty, GetMessage waits until a message is added to the queue.
The parameters wMsgFilterMin and wMsgFilterMax can be used to specify a range of messages to be retrieved. If both are 0, all messages are retrieved.
A common use of GetMessage is within a message loop, typically structured as follows:
MSG msg;
while (GetMessage(&msg, NULL, 0, 0)) {
TranslateMessage(&msg);
DispatchMessage(&msg);
}
If GetMessage returns -1, an error has occurred. If it returns 0, the application should terminate.
Requirements
- Minimum supported client: Windows 2000 Professional
- Minimum supported server: Windows 2000 Server
- Header:
winuser.h(includewindows.h) - Library: User32.lib
- DLL: User32.dll