Función GetMessage (winuser.h)
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
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) |
Consulte también
Conceptual
Referencia