PeekMessageW 函数 (winuser.h)

项目
08/27/2023

调度传入的非排队消息，检查线程消息队列中是否存在已发布的消息，并检索 (消息（如果存在任何) ）。

语法

BOOL PeekMessageW(
  [out]          LPMSG lpMsg,
  [in, optional] HWND  hWnd,
  [in]           UINT  wMsgFilterMin,
  [in]           UINT  wMsgFilterMax,
  [in]           UINT  wRemoveMsg
);

参数

[out] lpMsg

类型： LPMSG

指向接收消息信息的 MSG 结构的指针。

[in, optional] hWnd

类型：HWND

要检索其消息的窗口的句柄。窗口必须属于当前线程。

如果 hWnd 为 NULL，PeekMessage 将检索属于当前线程的任何窗口的消息，以及当前线程的消息队列中 hwnd 值为 NULL 的任何消息 (看到 MSG 结构) 。因此，如果 hWnd 为 NULL，则同时处理窗口消息和线程消息。

如果 hWnd 为 -1，则 PeekMessage 仅检索当前线程的消息队列中 hwnd 值为 NULL 的消息，即当 hWnd 参数为 NULL) 或 PostThreadMessage 时，PostMessage (发布的线程消息。

[in] wMsgFilterMin

类型： UINT

要检查的消息范围中第一条消息的值。使用 WM_KEYFIRST (0x0100) 指定第一条键盘消息， 或使用WM_MOUSEFIRST (0x0200) 指定第一条鼠标消息。

如果 wMsgFilterMin 和 wMsgFilterMax 均为零， 则 PeekMessage 将返回所有可用消息 (即，) 不执行范围筛选。

[in] wMsgFilterMax

类型： UINT

要检查的消息范围中最后一条消息的值。使用 WM_KEYLAST 指定最后一条键盘消息， WM_MOUSELAST 指定最后一条鼠标消息。

如果 wMsgFilterMin 和 wMsgFilterMax 均为零， 则 PeekMessage 将返回所有可用消息 (即，) 不执行范围筛选。

[in] wRemoveMsg

类型： UINT

指定如何处理消息。此参数可使用以下一个或多个值。

值	含义
PM_NOREMOVE 0x0000	PeekMessage 处理后不会从队列中删除消息。
PM_REMOVE 0x0001	PeekMessage 处理后，将从队列中删除消息。
PM_NOYIELD 0x0002	阻止系统释放正在等待调用方进入空闲状态的任何线程， (请参阅 WaitForInputIdle) 。将此值与 PM_NOREMOVE 或 PM_REMOVE组合在一起。

默认情况下，将处理所有消息类型。若要指定只应处理某些消息，请指定以下一个或多个值。

值	含义
PM_QS_INPUT (QS_INPUT << 16)	处理鼠标和键盘消息。
PM_QS_PAINT (QS_PAINT << 16)	处理画图消息。
PM_QS_POSTMESSAGE ( (QS_POSTMESSAGE \|QS_HOTKEY \|QS_TIMER) << 16)	处理所有已发布的消息，包括计时器和热键。
PM_QS_SENDMESSAGE << (QS_SENDMESSAGE 16)	处理所有已发送的消息。

返回值

类型： BOOL

如果消息可用，则返回值为非零。

如果没有可用的消息，则返回值为零。

注解

PeekMessage 检索与由 isChild 函数指定的 hWnd 参数或其任何子级标识的窗口关联的消息，并在 wMsgFilterMin 和 wMsgFilterMax 参数给出的消息值范围内。请注意，应用程序只能使用 wMsgFilterMin 和 wMsgFilterMax 参数中的低字;高字是为系统保留的。

请注意，无论为 wMsgFilterMin 和 wMsgFilterMax 指定哪些值，PeekMessage 始终检索WM_QUIT消息。

在此调用期间，系统将调度 (DispatchMessage) 挂起的非排队消息，即使用 SendMessage、SendMessageCallback、SendMessageTimeout 或 SendNotifyMessage 函数发送到调用线程拥有的窗口的消息。然后检索与指定筛选器匹配的第一个排队消息。系统还可以处理内部事件。如果未指定筛选器，则按以下顺序处理消息：

已发送消息
已发布的消息
输入 (硬件) 消息和系统内部事件
再次 () 发送消息
WM_PAINT 消息
WM_TIMER 消息

若要在发布消息之前检索输入消息，请使用 wMsgFilterMin 和 wMsgFilterMax 参数。

PeekMessage 函数通常不会从队列中删除WM_PAINT消息。 WM_PAINT 消息保留在队列中，直到它们得到处理。但是，如果 WM_PAINT 消息具有 NULL 更新区域， PeekMessage 会将其从队列中删除。

如果顶级窗口停止响应消息超过几秒钟，系统会认为窗口没有响应，并将其替换为具有相同 z 顺序、位置、大小和视觉属性的虚影窗口。这允许用户移动它、调整其大小，甚至关闭应用程序。但是，这些是唯一可用的操作，因为应用程序实际上没有响应。调试应用程序时，系统不会生成虚影窗口。

DPI 虚拟化

此 API 不参与 DPI 虚拟化。输出处于消息所面向的窗口的模式。不考虑调用线程。

示例

有关示例，请参阅检查消息队列。

注意

winuser.h 标头将 PeekMessage 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	winuser.h (包括 Windows.h)
Library	User32.lib
DLL	User32.dll
API 集	在 Windows 8) 中引入的 ext-ms-win-ntuser-message-l1-1-0 (