Функция PeekMessageW (winuser.h)

Статья
11/20/2024

Отправляет входящие неуправляемые сообщения, проверяет очередь сообщений потока для отправленного сообщения и извлекает сообщение (если оно существует).

Синтаксис

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

Дескриптор окна, сообщения которого необходимо извлечь. Окно должно принадлежать текущему потоку.

Если hWndNULL, PeekMessage извлекает сообщения для любого окна, которое принадлежит текущему потоку, и все сообщения в очереди сообщений текущего потока, значение NULL (см. структуру MSG). Таким образом, если hWnd null, обрабатываются сообщения окна и потоковые сообщения.

Если hWnd равно -1, PeekMessage извлекает только сообщения в очереди сообщений текущего потока, значением NULL, то есть потоковые сообщения, опубликованные PostMessage (если параметр hWnd имеет значение NULL 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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winuser.h (включая Windows.h)
библиотеки	User32.lib
DLL	User32.dll
набор API	ext-ms-win-ntuser-message-l1-1-0 (представлено в Windows 8)