winuser.h

Función PeekMessage

Despacha los mensajes de entrada enviados, comprueba la cola de mensajes del hilo en busca de un mensaje publicado, y lo recupera (si existe alguno).

Sintaxis

BOOL PeekMessageA(
    LPMSG lpMsg,
    HWND  hWnd,
    UINT  wMsgFilterMin,
    UINT  wMsgFilterMax,
    UINT  wRemoveMsg
);

Parámetros

lpMsg
Un puntero a una estructura MSG que recibe la información del mensaje.
hWnd

Un manipulador de ventana cuyos mensajes han de ser recuperados. La ventana debe pertenecer al hilo actual.

Si hWnd es NULL, PeekMessage recupera mensajes de cualquier ventana que pertenezca al hilo actual, y cualquier mensaje en la cola del hilo cuyo valor de hwnd sea NULL (ver la estructura MSG). Por lo tato, si hWnd es NULL, tanto los mensajes de ventana como los del hilo son procesados.

Si hWnd es -1, <PeekMessage recupera sólo mensajes en la cola actual del hilo cuyo valor de hwnd sea NULL, esto es, los mensajes del hilo publicados por PostMessage (cuando el parámetro hWnd sea NULL) o PostThreadMessage.

wMsgFilterMin

El valor del primer mensaje en el rango de mensajes a examinar. Usar WM_KEYFIRST (0x0100) para especificar el primer mensaje del teclado o WM_MOUSEFIRST (0x0200) para especificar el primer mensaje del ratón.

Si wMsgFilterMin y wMsgFilterMax son ambos cero, PeekMessage retorna todos los mensajes disponibles (es decir, no se aplica ningún filtro).

wMsgFilterMax

El valor del último mensaje en el rango de mensajes a examinar. Usar WM_KEYLAST para especificar el último mensaje del teclado o WM_MOUSELAST para especificar el último mensaje del ratón.

Si wMsgFilterMin y wMsgFilterMax son ambos cero, PeekMessage retorna todos los mensajes disponibles (es decir, no se aplica ningún filtro).

wRemoveMsg

Especifica cómo se deben manejar los mensajes. Este parámetro puede ser uno de los siguientes valores.

Valor Significado
PM_NOREMOVE
0x0000		 Los mensajes no son eliminados de la cola después de ser procesados por PeekMessage.
PM_REMOVE
0x0001		 Los mensajes son eliminados de la cola después de ser procesados por PeekMessage.
PM_NOYIELD
0x0002		 Evita que el sistema libere cualquier hilo que esté esperando a que el proceso que llama quede inactivo (ver WaitForInputIdle).
Se puede combinar este valor tanto con PM_NOREMOVE como con PM_REMOVE.

Por defecto, todos los mensajes son procesados. Para especificar que sólo ciertos mensajes deben ser procesados, especificar uno o más de los siguientes valores.

Valor Significado
PM_QS_INPUT
(QS_INPUT << 16)		 Procesa los mensajes del ratón y el teclado.
PM_QS_PAINT
(QS_PAINT << 16)		 Procesa los mensajes de pintado.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) << 16)		 Procesa todos los mensajes publicados, incluyendo timers y hotkeys.
PM_QS_SENDMESSAGE
(QS_SENDMESSAGE << 16)		 Procesa todos los mensajes enviados.

Valor de retorno

Si hay un mensaje disponible, el valor de retorno es distinto de cero.

Si no hay mensajes disponibles, el valor de retorno es cero.

Observaciones

PeekMessage recupera mensajes asociados con la ventana identificada por el parámetro hWnd o por cualquiera de ventanas hijas según lo especificado por la función IsChild, y dentro del rango de valores de mensaje dado por los parámetros wMsgFilterMin y wMsgFilterMax. Hay que tener en cuenta que una aplicación sólo puede usuar la palabra de menor peso en los parámetros wMsgFilterMin y wMsgFilterMax; la palabra de mayor peso está reservada para el sistema.

También hay que tener presente que PeekMessage siempre recupera los mensajes WM_QUIT, independientemente de los valores especificados para wMsgFilterMin y wMsgFilterMax.

Durante esta llamada, el sistema entrega los mensajes pendientes, no encolados, es decir, mensajes enviados a ventanas pertenecientes al hilo que realiza la llamada usando las funciones SendMessage, SendMessageCallback, SendMessageTimeout, or SendNotifyMessage. Entonces se recuperará el primer mensaje que coincida con el filtro especificado. El sistema también puede procesar eventos internos. Si no se especifica un filtro, los mensajes son procesados en el siguiente orden:

  • Mensajes enviados (send).
  • Mensajes publicados (post).
  • Mensajes de entrada (hardware) y eventos internos del sistema.
  • Mensajes enviados (otra vez).
  • Mensajes WM_PAINT.
  • Mensajes WM_TIMER.

Para recuperar mensaje de entrada (hardware) antes que mensajes publicados, se deben usar los parámetros wMsgFilterMin y wMsgFilterMax.

La función PeekMessage normalmente no elimina de la cola los mensajes WM_PAINT. Los mensajes WM_PAINT permanecen en la cola hasta que son procesados. Sin embargo, si un mensaje WM_PAINT tiene una región de actualización NULL, PeekMessage lo eliminará de la cola.

Si una ventana de mayor nivel deja de responder a mensajes por 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, posición, tamaño y atributos visuales. Esto permite al usuario moverla, redimensionarla o incluso cerrar la aplicación. Sin embargo, esas son las únicas acciones disponibles porque la aplicación no está respondiendo. Cuando una aplicación está siendo depurada, el sistema no genera una ventana fantasma.

Virtualización DPI

Esta API no participa en virtualización DPI. La salida está en el modo de la ventana a la que se dirige el mensaje. El hilo de llamada no se tiene en cuenta.

Nota: el fichero de cabecera winuser.h define PeekMessage como un alias que automáticamente selecciona la versión ANSI o Unicode de esta estructura a partir de la definición de la constante UNICODE del preprocesador. Mezclar el uso de alias de codificación neutral con código que no sea de codificación neutral puede producir desajustes que provoquen errores de compilación o en tiempo de ejecución. Para mayor información ver las convenciones sobre prototipos de funciones.