Функция GetMessage извлекает сообщение из очереди сообщений вызывающего потока и помещает его в заданную структуру. Эта функция регулирует поступление отправленных сообщений до тех пор, пока помещенное в очередь сообщение доступно для извлечения.
В отличие от GetMessage, функция PeekMessage не ждет, когда предыдущее помещенное в очередь сообщение возвратит значение.
Синтаксис
BOOL GetMessage( LPMSG lpMsg, HWND hWnd, UINT wMsgFilterMin, UINT wMsgFilterMax ); |
Параметры
lpMsg
[out] Указатель на структуру MSG, которая принимает информацию из очереди сообщений потока.
hWnd
[in] Дескриптор окна, чьи сообщения должны быть извлечены. Окно должно принадлежать вызывающему потоку. Значение ПУСТО (NULL) имеет специальное предназначение:
Значение |
Предназначение |
NULL |
GetMessage извлекает сообщения для любого окна, которое принадлежит вызывающему потоку и сообщения потока, помещенные в очередь вызывающего потока при помощи использования функции PostThreadMessage. |
wMsgFilterMin
[in] Определяет целочисленную величину самого маленького значения сообщения, которое будет извлечено. Используйте сообщение WM_KEYFIRST, чтобы задать первое сообщение клавиатуры или WM_MOUSEFIRST, чтобы задать первое сообщение мыши.Windows XP: Используйте сообщение WM_INPUT здесь и в параметре wMsgFilterMax, чтобы задать только сообщения WM_INPUT.
Если wMsgFilterMin и wMsgFilterMax являются оба нулевыми, функция GetMessage возвращает все доступные сообщения (то есть никакой фильтрации в диапазоне значений не выполняется).
wMsgFilterMax [in] Определяет целочисленную величину самого большого значения сообщения, которое будет извлечено. Используйте сообщение WM_KEYLAST, чтобы задать первое сообщение клавиатуры или WM_MOUSELAST, чтобы задать последнее сообщение мыши.Windows XP: Используйте сообщение WM_INPUT здесь и в параметре wMsgFilterMin, чтобы задать только сообщения WM_INPUT.
Если wMsgFilterMin и wMsgFilterMax являются оба нулевыми, функция GetMessage возвращает все доступные сообщения (то есть никакой фильтрации в диапазоне значений не выполняется).
Возвращаемые значения
Если функция извлекает какое-то сообщение, а не WM_QUIT, величина возвращаемого значения - не нуль.
Если функция извлекает сообщение WM_QUIT, величина возвращаемого значения - нуль.
Если имеется ошибка, величина возвращаемого значения - (минус)1. Например, функция завершается ошибкой, если hWnd - недопустимый дескриптор окна или lpMsg - недопустимый указатель. Чтобы получить дополнительные сведения об ошибке, вызовите функцию GetLastError.
Предупреждение !
Поскольку величина возвращаемого значения функции может быть не нуль, нуль или - (минус)1, не применяйте примерно такой код: while (GetMessage( lpMsg, hWnd, 0, 0)) ... Возможность возврата значения -(минус)1 означает, что такой код, может привести к фатальным ошибкам приложения. Вместо этого, используйте код подобно приведенному ниже: |
Пример
BOOL bRet; while( (bRet = GetMessage( &msg, NULL, 0, 0 )) != 0) { if (bRet == -1) { // Обработка ошибки и возможный выход из программы } 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 из очереди. Сообщения остаются в очереди до тех пор, пока не будут обработаны.
Windows XP: Если окно верхнего уровня останавливает ответ на сообщения в течение больше чем нескольких секунд, система рассматривает это окно как окно, которое зависло и заменяет его на ложное окно, которое имеет ту же самую Z - последовательность, местоположение, размер и визуальные атрибуты. Это дает возможность пользователю перемещать его, изменять его размеры, или даже закрыть приложение. Однако, это - единственные доступные действия, потому что приложение фактически зависает. Когда приложение в режиме отладчика, система не создает ложное окно.
Windows 95/98/Me: GetMessageW поддерживается подпрограммой Microsoft Layer for Unicode (MSLU). Чтобы использовать подпрограмму, Вы должны добавить некоторые файлы к вашему приложению, как это определено в Microsoft Layer for Unicode для систем Windows 95/98/Me.
Пример
Пример смотри в статье Создание цикла обработки сообщений.
Смотри также
Обзор Сообщения и очереди сообщений, IsChild, MSG, PeekMessage, PostMessage, PostThreadMessage, WaitMessage
Размещение и совместимость GetMessage |
|
Windows. NET Server |
Да |
Windows XP |
Да |
Windows 2000 |
Да |
Windows NT |
Да версии 3.1 и выше |
Windows Me |
Да |
Windows 98 |
Да |
Windows 95 |
Да |
Используемая библиотека |
User32.lib |
Заголовочный файл |
|
- объявлено в |
Winuser.h |
- включено в |
Windows.h |
Unicode |
Нет |
Замечания по платформе |
Не имеется |