GetMessage

2.x

The GetMessage function retrieves a message from the application's message queue and places the message in a MSG structure. If no message is available, GetMessage yields control to other applications until a message becomes available.

GetMessage retrieves messages associated only with the given window and within the given range of message values. The function does not retrieve messages for windows that belong to other applications.

Parameters

lpmsg

Points to an MSG structure that contains message information from the application's message queue. The MSG structure has the following form:

typedef struct tagMSG {     /* msg */
    HWND   hwnd;
    UINT   message;
    WPARAM wParam;
    LPARAM lParam;
    DWORD  time;
    POINT  pt;
} MSG;

For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.

hwnd

Identifies the window whose messages are to be retrieved. If this parameter is NULL, GetMessage retrieves messages for any window that belongs to the application making the call.

uMsgFilterMin

Specifies the integer value of the lowest message value to be retrieved.

uMsgFilterMax

Specifies the integer value of the highest message value to be retrieved.

Return Value

The return value is nonzero if a message other than WM_QUIT is retrieved. It is zero if the WM_QUIT message is retrieved.

Comments

The return value is usually used to decide whether to terminate the application's main loop and exit the program.

The WM_KEYFIRST and WM_KEYLAST constants can be used as filter values to retrieve all messages related to keyboard input; the WM_MOUSEFIRST and WM_MOUSELAST constants can be used to retrieve all mouse-related messages. If the uMsgFilterMin and uMsgFilterMax parameters are both zero, the GetMessage function returns all available messages (without performing any filtering).

In addition to yielding control to other applications when no messages are available, the GetMessage and PeekMessage functions also yield control when WM_PAINT or WM_TIMER messages for other tasks are available.

The GetMessage, PeekMessage, and WaitMessage functions are the only ways to let other applications run. If your application does not call any of these functions for long periods of time, other applications cannot run.

Example

The following example uses the GetMessage function to retrieve messages from a message queue, translates virtual-key messages into character messages, and dispatches messages to the appropriate window procedures:

MSG msg;

while (GetMessage(&msg, (HWND) NULL, 0, 0)) {
    TranslateMessage(&msg);
    DispatchMessage(&msg);
}

See Also

GetMessageExtraInfo, PeekMessage, PostQuitMessage, SetMessageQueue, WaitMessage