PeekMessageA 函数（winuser.h）

项目
11/20/2024

调度传入的非排队消息，检查已发布的消息的线程消息队列，并检索消息（如果有）。

语法

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

参数

[out] lpMsg

类型：LPMSG

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

[in, optional] hWnd

类型：HWND

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

如果 hWndNULL，PeekMessage 检索属于当前线程的任何窗口的消息，并且当前线程的消息队列上 hwnd 值 NULL（请参阅 MSG 结构）。因此，如果 hWnd NULL，则会处理窗口消息和线程消息。

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

[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 检索与由 hWnd 参数或其任何子项标识的消息，如 isChild 函数指定的 wMsgFilterMin 和 wMsgFilterMax 参数指定的消息值范围内。请注意，应用程序只能在 wMsgFilterMin 中使用低字，wMsgFilterMax 参数;为系统保留高字。

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

在此调用期间，系统会调度（DispatchMessage）挂起的非排队消息，即使用 sendMessageSendMessage、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 [仅限桌面应用]
目标平台	窗户
标头	winuser.h （包括 Windows.h）
库	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-message-l1-1-0（在 Windows 8 中引入）