GetMessage函数

GetMessage函数从调用线程的消息队列中获取一个消息。该函数派送“发送消息”（非队列消息），直到取得一个可用的投递消息。

PeekMessage与GetMessage不同，PeekMessage不会等待有消息被投递才返回（言下之意就是，GetMessage函数会一直等待直到有消息被投递才会返回）。

函数原型：

BOOL GetMessage(        

 LPMSG lpMsg,

    HWND hWnd,

    UINT wMsgFilterMin,

    UINT wMsgFilterMax

);

参数说明：

lpMsg：指向一个MSG结构的指针，该结构中保存着从线程消息队列中取得的消息信息。

hWnd：取得消息的相关窗口句柄。该窗口必须属于正在调用的线程。NULL值有其特殊含义：GetMessage检索任何属于调用线程窗口的消息，并且通过PostThreadMessage函数将线程消息发送到调用线程。

wMsgFilterMin：指定被检索的最小消息值的整数。使用WM_KEYFIRST指定第一个键盘消息或WM_MOUSEFIRST指定第一个鼠标消息。

wMsgFilterMax：指定被检索的最大消息值的整数。使用WM_KEYLAST指定最后的键盘消息或WM_MOUSEFIRST指定最后的鼠标消息。

Windows XP：在wMsgFilterMin和wMsgFilterMax中指定WM_INPUT，则只获得WM_INPUT消息。

如果将wMsgFilterMin和wMsgFilterMax都指定为0，GetMessage函数会返回所有可用的消息（此时并没有设置消息的筛选范围）。

返回值：

如果函数检索到的消息不是WM_QUIT消息，则返回非0值。

如果函数检索到了WM_QUIT消息，则返回0值。

如果发生错误，返回值为-1。例如，参数hWnd是一个无效的窗口句柄或lpMsg是一个无效的指针。要获得更多的错误信息可以调用GetLastError函数。

警告：

因为函数的返回值可以为非0、0或-1，应该避免如下的代码：

while(GetMessage( lpMsg, hWnd, 0, 0)) ...

当出现GetMessage的返回值为-1时，将可能导致程序的致命错误。

使用如下的代码代替：

BOOL bRet;

 

while( (bRet = GetMessage( &msg, NULL, 0, 0 )) !=0)

{

    if (bRet == -1)

    {

        // handle the error and possibly exit

    }

    else

    {

        TranslateMessage(&msg);

        DispatchMessage(&msg);

    }

}

注意事项：

程序通常使用返回值来确定是否应该结束主消息循环并退出程序。

GetMessage函数检索由hWnd参数标识的关联窗体，或者由IsChild函数指定的它们子窗体的消息，并且消息范围在wMsgFilterMin和wMsgFilterMax参数指定值之间的消息。注意，应用只能用wMsgFilterMin和wMsgFilterMax参数的低字位，高字位是为系统保留的。

注意，不管在wMsgFilterMin和wMsgFilterMax指定的范围如何，GetMassage函数总是检索会WM_QUIT消息。

在函数调用期间，系统用SendMessage、SendMessageCallback,、SendMessageTimeout或者SendNotifyMessage函数发送待处理的、非队列的消息给属于当前线程的窗口。系统也可能处理内部事件。消息的处理顺序如下：

 Sentmessages(发送消息)

 Postedmessages（投递消息）

 输入（硬件）消息或者系统内部事件

 Sentmessages (again)（发送消息）

WM_PAINT消息

WM_TIMER消息

在投递消息之前检索输入消息，可以利用wMsgFilterMin和wMsgFilterMax参数做检索设置。

GetMessage不会从消息队列中移除WM_PAINT消息。该消息将一直存在于消息队列中直到被处理。

//原文如下：

The GetMessage function retrieves a message from the calling thread's message queue. The function dispatches incoming sent messages until a posted message is available for retrieval.

Unlike GetMessage, the PeekMessage function does not wait for a message to be posted before returning.

Syntax

BOOL GetMessage(      

    LPMSG lpMsg,
    HWND hWnd,
    UINT wMsgFilterMin,
    UINT wMsgFilterMax
);

Parameters

lpMsg

[out] Pointer to an MSG structure that receives message information from the thread's message queue.

hWnd

[in] Handle to the window whose messages are to be retrieved. The window must belong to the calling thread. The NULL value has a special meaning:

NULL

GetMessage retrieves messages for any window that belongs to the calling thread and thread messages posted to the calling thread using the PostThreadMessage function.

wMsgFilterMin

[in] Specifies the integer value of the lowest message value to be retrieved. Use WM_KEYFIRST to specify the first keyboard message or WM_MOUSEFIRST to specify the first mouse message.

Windows XP: Use WM_INPUT here and in wMsgFilterMax to specify only theWM_INPUT messages.

If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no range filtering is performed).

wMsgFilterMax

[in] Specifies the integer value of the highest message value to be retrieved. Use WM_KEYLAST to specify the last keyboard message or WM_MOUSELAST to specify the last mouse message.

Windows XP: Use WM_INPUT here and in wMsgFilterMin to specify only theWM_INPUT messages.

If wMsgFilterMin and wMsgFilterMax are both zero, GetMessage returns all available messages (that is, no range filtering is performed).

Return Value

If the function retrieves a message other than WM_QUIT, the return value is nonzero.

If the function retrieves the WM_QUIT message, the return value is zero.

If there is an error, the return value is -1. For example, the function fails ifhWnd is an invalid window handle orlpMsg is an invalid pointer. To get extended error information, call GetLastError.

Warning  

Because the return value can be nonzero, zero, or -1, avoid code like this:

while (GetMessage( lpMsg, hWnd, 0, 0)) ...

The possibility of a -1 return value means that such code can lead to fatal application errors. Instead, use code like this:

Hide Example

BOOL bRet;

while( (bRet = GetMessage( &msg, NULL, 0, 0 )) != 0)
{ 
    if (bRet == -1)
    {
        // handle the error and possibly exit
    }
    else
    {
        TranslateMessage(&msg); 
        DispatchMessage(&msg); 
    }
}

Remarks

An application typically uses the return value to determine whether to end the main message loop and exit the program.

The GetMessage function retrieves messages associated with the window identified by thehWnd parameter or any of its children, as specified by the IsChild function, and within the range of message values given by thewMsgFilterMin and wMsgFilterMax parameters. Note that an application can only use the low word in thewMsgFilterMin andwMsgFilterMax parameters; the high word is reserved for the system.

Note that GetMessage always retrievesWM_QUIT messages, no matter which values you specify forwMsgFilterMin andwMsgFilterMax.

During this call, the system delivers pending messages that were sent to windows owned by the calling thread using the SendMessage, SendMessageCallback, SendMessageTimeout, or SendNotifyMessage function. The system may also process internal events. Messages are processed in the following order:

• Sent messages
• Posted messages
• Input (hardware) messages and system internal events
• Sent messages (again)
• WM_PAINT messages
• WM_TIMER messages

To retrieve input messages before posted messages, use the wMsgFilterMin andwMsgFilterMax parameters.

GetMessage does not removeWM_PAINT messages from the queue. The messages remain in the queue until processed.

Windows XP: If a top-level window stops responding to messages for more than several seconds, the system considers the window to be not responding and replaces it with a ghost window that has the same z-order, location, size, and visual attributes. This allows the user to move it, resize it, or even close the application. However, these are the only actions available because the application is actually not responding. When in the debugger mode, the system does not generate a ghost window.

Windows 95/98/Me: GetMessageW is supported by the Microsoft Layer for Unicode (MSLU). To use this, you must add certain files to your application, as outlined in Microsoft Layer for Unicode on Windows 95/98/Me Systems.