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 |
|---|---|
|
Les messages ne sont pas supprimés de la file d’attente après le traitement par PeekMessage. |
|
Les messages sont supprimés de la file d’attente après traitement par PeekMessage. |
|
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 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
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
Messages et files d’attente de messages
Autres ressources
Référence