Función PeekMessageA (winuser.h)

  • Artículo

Envía mensajes entrantes no puestos en cola, comprueba la cola de mensajes de subprocesos de un mensaje publicado y recupera el mensaje (si existe alguno).

Sintaxis

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

Parámetros

[out] lpMsg

Tipo: LPMSG

Puntero a una estructura MSG que recibe información del mensaje.

[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, PeekMessage recupera los mensajes de 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, PeekMessage recupera solo los mensajes de la cola de mensajes del subproceso actual cuyo valor hwnd es NULL, es decir, los mensajes de subproceso que publica PostMessage (cuando el parámetro hWnd es NULL) o PostThreadMessage.

[in] wMsgFilterMin

Tipo: UINT

Valor del primer mensaje del intervalo de mensajes que se van a examinar. Use WM_KEYFIRST (0x0100) para especificar el primer mensaje de teclado o WM_MOUSEFIRST (0x0200) para especificar el primer mensaje del mouse.

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

[in] wMsgFilterMax

Tipo: UINT

Valor del último mensaje del intervalo de mensajes que se van a examinar. Use WM_KEYLAST para especificar el último mensaje de teclado o WM_MOUSELAST para especificar el último mensaje del mouse.

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

[in] wRemoveMsg

Tipo: UINT

Especifica cómo se van a controlar los mensajes. Este parámetro puede ser uno o más de los siguientes valores.

Valor Significado
PM_NOREMOVE
0x0000
 PeekMessage no quita los mensajes de la cola después del procesamiento.
PM_REMOVE
0x0001
 PeekMessage quita los mensajes de la cola después del procesamiento.
PM_NOYIELD
0x0002
 Impide que el sistema libere cualquier subproceso que esté esperando a que el autor de la llamada vaya inactivo (consulte WaitForInputIdle).

Combine este valor con PM_NOREMOVE o PM_REMOVE.
 

De forma predeterminada, se procesan todos los tipos de mensajes. Para especificar que solo se debe procesar un mensaje determinado, especifique uno o varios de los valores siguientes.

Valor Significado
PM_QS_INPUT
(QS_INPUT << 16)
 Procesar mensajes de mouse y teclado.
PM_QS_PAINT
(QS_PAINT << 16)
 Procesar mensajes de pintura.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) << 16)
 Procese todos los mensajes publicados, incluidos temporizadores y teclas de acceso rápido.
PM_QS_SENDMESSAGE
(QS_SENDMESSAGE << 16)
 Procesar todos los mensajes enviados.

Valor devuelto

Tipo: BOOL

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

Si no hay mensajes disponibles, el valor devuelto es cero.

Comentarios

PeekMessage 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 PeekMessage siempre recupera WM_QUIT mensajes, independientemente de los valores que especifique para wMsgFilterMin y wMsgFilterMax.

Durante esta llamada, el sistema envía 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:

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

La función PeekMessage normalmente no quita WM_PAINT mensajes de la cola. WM_PAINT mensajes permanecen en la cola hasta que se procesan. Sin embargo, si un mensaje de WM_PAINT tiene una región de actualización NULL , PeekMessage la quita de la cola.

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 se depura una aplicación, 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, vea Examinar una cola de mensajes.

Nota

El encabezado winuser.h define PeekMessage 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)

Consulte también

Conceptual

GetMessage

IsChild

MSG

Mensajes y colas de mensajes

Otros recursos

Referencia

WaitForInputIdle

WaitMessage