Функция 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, то есть сообщения потоков, опубликованные PostMessage (если параметр hWnd имеет значение NULL) или PostThreadMessage.

[in] wMsgFilterMin

Тип: UINT

Значение первого сообщения в диапазоне проверяемых сообщений. Используйте WM_KEYFIRST (0x0100), чтобы указать первое сообщение клавиатуры, или WM_MOUSEFIRST (0x0200), чтобы указать первое сообщение мыши.

Если значения wMsgFilterMin и wMsgFilterMax равны нулю, PeekMessage возвращает все доступные сообщения (то есть фильтрация по диапазонам не выполняется).

[in] wMsgFilterMax

Тип: UINT

Значение последнего сообщения в диапазоне сообщений для проверки. Используйте WM_KEYLAST , чтобы указать последнее сообщение клавиатуры, или WM_MOUSELAST , чтобы указать последнее сообщение мыши.

[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) ожидающие сообщения без очереди, то есть сообщения, отправленные в окна, принадлежащие вызывающей цепочке, с помощью функции 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-message-l1-1-0 (появилось в Windows 8)