PeekMessageA, fonction (winuser.h)

Distribue les messages entrants non mis en file d’attente, recherche dans la file d’attente de messages de thread un message publié et récupère le message (le cas échéant).

Syntaxe

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

Paramètres

[out] lpMsg

Type : LPMSG

Pointeur vers une structure MSG qui reçoit des informations de message.

[in, optional] hWnd

Type : HWND

Handle de la fenêtre dont les messages doivent être récupérés. La fenêtre doit appartenir au thread actuel.

Si hWnd a la valeur NULL, PeekMessage récupère les messages pour toutes les fenêtres qui appartiennent au thread actuel, ainsi que tous les messages de la file d’attente de messages du thread actuel dont la valeur hwnd est NULL (voir la structure MSG ). Par conséquent, si hWnd a la valeur NULL, les messages de fenêtre et les messages de thread sont traités.

Si hWnd a la valeur -1, PeekMessage récupère uniquement les messages de la file d’attente de messages du thread actuel dont la valeur hwnd est NULL, c’est-à-dire les messages de thread tels que publiés par PostMessage (lorsque le paramètre hWnd a la valeur NULL) ou PostThreadMessage.

[in] wMsgFilterMin

Type : UINT

Valeur du premier message dans la plage de messages à examiner. Utilisez WM_KEYFIRST (0x0100) pour spécifier le premier message clavier ou WM_MOUSEFIRST (0x0200) pour spécifier le premier message de la souris.

Si wMsgFilterMin et wMsgFilterMax sont tous deux zéro, PeekMessage retourne tous les messages disponibles (autrement dit, aucun filtrage de plage n’est effectué).

[in] wMsgFilterMax

Type : UINT

Valeur du dernier message dans la plage de messages à examiner. Utilisez WM_KEYLAST pour spécifier le dernier message clavier ou WM_MOUSELAST pour spécifier le dernier message de la souris.

Si wMsgFilterMin et wMsgFilterMax sont tous deux zéro, PeekMessage retourne tous les messages disponibles (autrement dit, aucun filtrage de plage n’est effectué).

[in] wRemoveMsg

Type : UINT

Spécifie comment les messages doivent être gérés. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.

Valeur Signification
PM_NOREMOVE
0x0000
Les messages ne sont pas supprimés de la file d’attente après le traitement par PeekMessage.
PM_REMOVE
0x0001
Les messages sont supprimés de la file d’attente après traitement par PeekMessage.
PM_NOYIELD
0x0002
Empêche le système de libérer tout thread qui attend que l’appelant soit inactif (voir WaitForInputIdle).

Combinez cette valeur avec PM_NOREMOVE ou PM_REMOVE.

 

Par défaut, tous les types de messages sont traités. Pour spécifier que seul un message doit être traité, spécifiez une ou plusieurs des valeurs suivantes.

Valeur Signification
PM_QS_INPUT
(16 QS_INPUT << )
Traiter les messages de souris et de clavier.
PM_QS_PAINT
(16 QS_PAINT << )
Traiter les messages de peinture.
PM_QS_POSTMESSAGE
((QS_POSTMESSAGE | QS_HOTKEY | QS_TIMER) << 16)
Traitez tous les messages publiés, y compris les minuteurs et les touches d’accès rapide.
PM_QS_SENDMESSAGE
(16 QS_SENDMESSAGE << )
Traiter tous les messages envoyés.

Valeur retournée

Type : BOOL

Si un message est disponible, la valeur de retour est différente de zéro.

Si aucun message n’est disponible, la valeur de retour est zéro.

Remarques

PeekMessage récupère les messages associés à la fenêtre identifiée par le paramètre hWnd ou l’un de ses enfants, comme spécifié par la fonction IsChild , et dans la plage de valeurs de message données par les paramètres wMsgFilterMin et wMsgFilterMax . Notez qu’une application peut uniquement utiliser le mot faible dans les paramètres wMsgFilterMin et wMsgFilterMax ; le mot haut est réservé au système.

Notez que PeekMessage récupère toujours WM_QUIT messages, quelles que soient les valeurs que vous spécifiez pour wMsgFilterMin et wMsgFilterMax.

Pendant cet appel, le système distribue (DispatchMessage) les messages en attente et sans file d’attente, c’est-à-dire les messages envoyés aux fenêtres appartenant au thread appelant à l’aide de la fonction SendMessage, SendMessageCallback, SendMessageTimeout ou SendNotifyMessage . Ensuite, le premier message mis en file d’attente qui correspond au filtre spécifié est récupéré. Le système peut également traiter des événements internes. Si aucun filtre n’est spécifié, les messages sont traités dans l’ordre suivant :

  • Messages envoyés
  • Messages publiés
  • Messages d’entrée (matériel) et événements internes système
  • Messages envoyés (à nouveau)
  • WM_PAINT messages
  • WM_TIMER messages
Pour récupérer les messages d’entrée avant la publication des messages, utilisez les paramètres wMsgFilterMin et wMsgFilterMax .

La fonction PeekMessage ne supprime normalement pas WM_PAINT messages de la file d’attente. WM_PAINT messages restent dans la file d’attente jusqu’à ce qu’ils soient traités. Toutefois, si un message WM_PAINT a une région de mise à jour NULL , PeekMessage le supprime de la file d’attente.

Si une fenêtre de niveau supérieur cesse de répondre aux messages pendant plus de plusieurs secondes, le système considère que la fenêtre ne répond pas et la remplace par une fenêtre fantôme qui a le même ordre de plan, l’emplacement, la même taille et les mêmes attributs visuels. Cela permet à l’utilisateur de le déplacer, de le redimensionner ou même de fermer l’application. Toutefois, il s’agit des seules actions disponibles, car l’application ne répond pas. Lorsqu’une application est en cours de débogage, le système ne génère pas de fenêtre fantôme.

Virtualisation PPP

Cette API ne participe pas à la virtualisation PPP. La sortie est dans le mode de la fenêtre ciblée par le message. Le thread appelant n’est pas pris en compte.

Exemples

Pour obtenir un exemple, consultez Examen d’une file d’attente de messages.

Notes

L’en-tête winuser.h définit PeekMessage en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge Windows 2000 Server [applications de bureau uniquement]
Plateforme cible Windows
En-tête winuser.h (inclure Windows.h)
Bibliothèque User32.lib
DLL User32.dll
Ensemble d’API ext-ms-win-ntuser-message-l1-1-0 (introduit dans Windows 8)

Voir aussi

Conceptuel

GetMessage

IsChild

MSG

Messages et files d’attente de messages

Autres ressources

Référence

WaitForInputIdle

WaitMessage