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

Статья
08/27/2023

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

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

Синтаксис

BOOL GetMessageA(
  [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. Выходные данные будут в режиме окна, на которое нацелено сообщение. Вызывающий поток не учитывается.

Примеры

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

Примечание

Заголовок winuser.h определяет GetMessage в качестве псевдонима, который автоматически выбирает версию 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)