Функция GetMessage

Функция 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.

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

Если функция извлекает какое-то сообщение, а не 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	Нет
Замечания по платформе	Не имеется

Назад в оглавление

На главную страницу

На оглавление справки