Función GetMessage (winuser.h)

Artículo
03/04/2024

Recupera un mensaje de la cola de mensajes del subproceso de llamada. La función envía los mensajes enviados entrantes hasta que un mensaje publicado esté disponible para su recuperación.

Sin embargo, GetMessage funciona como PeekMessage, pero GetMessage se bloquea hasta que se publica un mensaje antes de devolverlo.

Sintaxis

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

Parámetros

[out] lpMsg

Tipo: LPMSG

Puntero a una estructura MSG que recibe información de mensajes de la cola de mensajes del subproceso.

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana cuyos mensajes se van a recuperar. La ventana debe pertenecer al subproceso actual.

Si hWnd es NULL, GetMessage recupera mensajes para cualquier ventana que pertenezca al subproceso actual y cualquier mensaje de la cola de mensajes del subproceso actual cuyo valor hwnd sea NULL (vea la estructura MSG ). Por lo tanto, si hWnd es NULL, se procesan los mensajes de ventana y los mensajes de subproceso.

Si hWnd es -1, GetMessage recupera solo los mensajes de la cola de mensajes del subproceso actual cuyo valor hwnd es NULL, es decir, los mensajes de subproceso publicados por PostMessage (cuando el parámetro hWnd es NULL) o PostThreadMessage.

[in] wMsgFilterMin

Tipo: UINT

Valor entero del valor de mensaje más bajo que se va a recuperar. Use WM_KEYFIRST (0x0100) para especificar el primer mensaje de teclado o WM_MOUSEFIRST (0x0200) para especificar el primer mensaje del mouse.

Use WM_INPUT aquí y en wMsgFilterMax para especificar solo los mensajes WM_INPUT .

Si wMsgFilterMin y wMsgFilterMax son cero, GetMessage devuelve todos los mensajes disponibles (es decir, no se realiza ningún filtrado de intervalo).

[in] wMsgFilterMax

Tipo: UINT

Valor entero del valor de mensaje más alto que se va a recuperar. Use WM_KEYLAST para especificar el último mensaje de teclado o WM_MOUSELAST para especificar el último mensaje del mouse.

Use WM_INPUT aquí y en wMsgFilterMin para especificar solo los mensajes WM_INPUT .

Si wMsgFilterMin y wMsgFilterMax son cero, GetMessage devuelve todos los mensajes disponibles (es decir, no se realiza ningún filtrado de intervalo).

Valor devuelto

Tipo: BOOL

Si la función recupera un mensaje distinto de WM_QUIT, el valor devuelto es distinto de cero.

Si la función recupera el mensaje WM_QUIT , el valor devuelto es cero.

Si se produce un error, el valor devuelto es -1. Por ejemplo, la función produce un error si hWnd es un identificador de ventana no válido o lpMsg es un puntero no válido. Para obtener información de error extendida, llame a GetLastError.

Dado que el valor devuelto puede ser distinto de cero, cero o -1, evite el código como este:

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

La posibilidad de un valor devuelto -1 en el caso de que hWnd sea un parámetro no válido (como hacer referencia a una ventana que ya se ha destruido) significa que este código puede provocar errores graves de aplicación. En su lugar, use código similar al siguiente:

BOOL bRet;

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

Comentarios

Normalmente, una aplicación usa el valor devuelto para determinar si finalizar el bucle de mensajes principal y salir del programa.

La función GetMessage recupera los mensajes asociados a la ventana identificada por el parámetro hWnd o cualquiera de sus elementos secundarios, tal y como especifica la función IsChild , y dentro del intervalo de valores de mensaje proporcionados por los parámetros wMsgFilterMin y wMsgFilterMax . Tenga en cuenta que una aplicación solo puede usar la palabra baja en los parámetros wMsgFilterMin y wMsgFilterMax ; la palabra alta está reservada para el sistema.

Tenga en cuenta que GetMessage siempre recupera WM_QUIT mensajes, independientemente de los valores que especifique para wMsgFilterMin y wMsgFilterMax.

Durante esta llamada, el sistema entrega mensajes pendientes y no puestos en cola, es decir, mensajes enviados a ventanas propiedad del subproceso de llamada mediante la función SendMessage, SendMessageCallback, SendMessageTimeout o SendNotifyMessage . A continuación, se recupera el primer mensaje en cola que coincide con el filtro especificado. El sistema también puede procesar eventos internos. Si no se especifica ningún filtro, los mensajes se procesan en el orden siguiente:

Mensajes enviados
Mensajes publicados
Mensajes de entrada (hardware) y eventos internos del sistema
Mensajes enviados (de nuevo)
WM_PAINT mensajes
mensajes de WM_TIMER

Para recuperar mensajes de entrada antes de los mensajes publicados, use los parámetros wMsgFilterMin y wMsgFilterMax .

GetMessage no quita WM_PAINT mensajes de la cola. Los mensajes permanecen en la cola hasta que se procesan.

Si una ventana de nivel superior deja de responder a los mensajes durante más de varios segundos, el sistema considera que la ventana no responde y la reemplaza por una ventana fantasma que tiene el mismo orden Z, ubicación, tamaño y atributos visuales. Esto permite al usuario moverlo, cambiar su tamaño o incluso cerrar la aplicación. Sin embargo, estas son las únicas acciones disponibles porque la aplicación realmente no responde. Cuando está en el modo del depurador, el sistema no genera una ventana fantasma.

Virtualización de PPP

Esta API no participa en la virtualización de PPP. La salida está en el modo de la ventana a la que el mensaje tiene como destino. No se tiene en cuenta el subproceso que realiza la llamada.

Ejemplos

Para obtener un ejemplo, consulte Creación de un bucle de mensajes.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-message-l1-1-0 (introducido en Windows 8)