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

Статья
11/20/2024

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

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

Синтаксис

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

Параметры

[out] lpMsg

Тип: LPMSG

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

[in, optional] hWnd

Тип: HWND

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

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

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