Función GetMessageA (winuser.h)

Artículo
08/27/2023

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

A diferencia de GetMessage, la función PeekMessage no espera a que se publique un mensaje antes de devolverlo.

Sintaxis

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

Parámetros

[out] lpMsg

Tipo: LPMSG

Puntero a una estructura de MSG que recibe información del mensaje 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 los mensajes de cualquier ventana que pertenezca al subproceso actual y los mensajes 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 de WM_INPUT .

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

[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 de WM_INPUT .

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

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 código similar al siguiente:

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 (por ejemplo, hacer referencia a una ventana que ya se ha destruido) significa que este código puede provocar errores de aplicación irrecuperables. 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, según lo especificado por 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 que pertenecen al 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)
mensajes de WM_PAINT
mensajes de WM_TIMER

Para recuperar los 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 moverla, 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 de destino del mensaje. No se tiene en cuenta el subproceso que realiza la llamada.

Ejemplos

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

Nota

El encabezado winuser.h define GetMessage como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

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 (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll
Conjunto de API	ext-ms-win-ntuser-message-l1-1-0 (introducido en Windows 8)