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

Статья
03/11/2023

Извлекает сообщение из очереди сообщений вызывающего потока. Функция отправляет входящие отправленные сообщения до тех пор, пока отправленное сообщение не будет доступно для получения.

Однако функции GetMessage, такие как PeekMessage, GetMessage блокируется, пока сообщение не будет опубликовано перед возвратом.

Синтаксис

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

Параметры

[out] lpMsg

Тип: LPMSG

Указатель на структуру MSG , которая получает сведения о сообщениях из очереди сообщений потока.

[in, optional] hWnd

Тип: HWND

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

Если hWnd имеет значение NULL, GetMessage извлекает сообщения для любого окна, относящегося к текущему потоку, и всех сообщений в очереди сообщений текущего потока, значение hwnd которого равно NULL (см. структуру MSG ). Поэтому, если hWnd имеет значение NULL, обрабатываются сообщения окон и потоки.

Если значение hWnd равно -1, GetMessage получает только сообщения в очереди сообщений текущего потока, hwnd которых равно NULL, то есть сообщения потока, опубликованные PostMessage (если параметр hWnd имеет значение NULL) или PostThreadMessage.

[in] wMsgFilterMin

Тип: UINT

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

Используйте WM_INPUT здесь и в wMsgFilterMax , чтобы указать только WM_INPUT сообщений.

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

[in] wMsgFilterMax

Тип: UINT

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

Используйте WM_INPUT здесь и в wMsgFilterMin , чтобы указать только WM_INPUT сообщений.

Возвращаемое значение

Тип: BOOL

Если функция получает сообщение, отличное от WM_QUIT, возвращается ненулевое значение.

Если функция получает WM_QUIT сообщение, возвращаемое значение равно нулю.

При возникновении ошибки возвращается значение -1. Например, функция завершается ошибкой, если hWnd является недопустимым дескриптором окна или lpMsg является недопустимым указателем. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Так как возвращаемое значение может быть ненулевое, нулевое или -1, избегайте следующего кода:

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

Возможность возвращаемого значения -1 в случае, если hWnd является недопустимым параметром (например, ссылкой на окно, которое уже было уничтожено), означает, что такой код может привести к неустранимым ошибкам приложения. Вместо этого используйте следующий код:

BOOL bRet;

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

Функция GetMessage извлекает сообщения, связанные с окном, определенным параметром hWnd или любым из его дочерних элементов, как указано в функции IsChild , и в диапазоне значений сообщений, заданных параметрами wMsgFilterMin и wMsgFilterMax . Обратите внимание, что приложение может использовать только низкое слово в параметрах wMsgFilterMin и wMsgFilterMax ; высокое слово зарезервировано для системы.

Обратите внимание, что GetMessage всегда извлекает WM_QUIT сообщения, независимо от того, какие значения заданы для wMsgFilterMin и wMsgFilterMax.

Во время этого вызова система доставляет ожидающие сообщения без очереди, то есть сообщения, отправленные в окна, принадлежащие вызывающей цепочке, с помощью функции SendMessage , SendMessageCallback, SendMessageTimeout или SendNotifyMessage. Затем извлекается первое сообщение в очереди, соответствующее указанному фильтру. Система также может обрабатывать внутренние события. Если фильтр не указан, сообщения обрабатываются в следующем порядке:

Отправленные сообщения
Опубликованные сообщения
Входные (аппаратные) сообщения и внутренние события системы
Отправленные сообщения (снова)
WM_PAINT сообщений
WM_TIMER сообщений

Чтобы получить входные сообщения перед опубликованными сообщениями, используйте параметры wMsgFilterMin и wMsgFilterMax .

GetMessage не удаляет WM_PAINT сообщения из очереди. Сообщения остаются в очереди до тех пор, пока не будут обработаны.

Если окно верхнего уровня перестает отвечать на сообщения более нескольких секунд, система считает, что окно не отвечает, и заменяет его фантомным окном с одинаковыми Z-порядком, расположением, размером и визуальными атрибутами. Это позволяет пользователю перемещать его, изменять размер или даже закрывать приложение. Однако это единственные доступные действия, так как приложение фактически не отвечает. В режиме отладчика система не создает фантомное окно.

Виртуализация DPI

Этот API не участвует в виртуализации DPI. Выходные данные будут в режиме окна, на которое нацелено сообщение. Вызывающий поток не учитывается.

Примеры

Пример см. в разделе Создание цикла сообщений.

Требования

Требование	Значение
Минимальная версия клиента	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)