GetMessageA, fonction (winuser.h)
Récupère un message à partir de la file d’attente de messages du thread appelant. La fonction distribue les messages envoyés entrants jusqu’à ce qu’un message publié soit disponible pour la récupération.
Contrairement à GetMessage, la fonction PeekMessage n’attend pas qu’un message soit publié avant de retourner.
Syntaxe
BOOL GetMessageA(
[out] LPMSG lpMsg,
[in, optional] HWND hWnd,
[in] UINT wMsgFilterMin,
[in] UINT wMsgFilterMax
);
Paramètres
[out] lpMsg
Type : LPMSG
Pointeur vers une structure MSG qui reçoit des informations de message de la file d’attente de messages du thread.
[in, optional] hWnd
Type : HWND
Handle vers la fenêtre dont les messages doivent être récupérés. La fenêtre doit appartenir au thread actuel.
Si
Si
[in] wMsgFilterMin
Type : uiNT
Valeur entière de la valeur de message la plus basse à récupérer. Utilisez WM_KEYFIRST (0x0100) pour spécifier le premier message clavier ou WM_MOUSEFIRST (0x0200) pour spécifier le premier message de la souris.
Utilisez WM_INPUT ici et dans wMsgFilterMax pour spécifier uniquement les messages WM_INPUT.
Si wMsgFilterMin et wMsgFilterMax sont à la fois zéro, GetMessage retourne tous les messages disponibles (autrement dit, aucun filtrage de plage n’est effectué).
[in] wMsgFilterMax
Type : uiNT
Valeur entière de la valeur de message la plus élevée à récupérer. Utilisez WM_KEYLAST pour spécifier le dernier message clavier ou WM_MOUSELAST pour spécifier le dernier message de la souris.
Utilisez WM_INPUT ici et dans wMsgFilterMin pour spécifier uniquement les messages WM_INPUT.
Si wMsgFilterMin et wMsgFilterMax sont à la fois zéro, GetMessage retourne tous les messages disponibles (autrement dit, aucun filtrage de plage n’est effectué).
Valeur de retour
Type : BOOL
Si la fonction récupère un message autre que WM_QUIT, la valeur de retour est différente de zéro.
Si la fonction récupère le message WM_QUIT, la valeur de retour est égale à zéro.
En cas d’erreur, la valeur de retour est -1. Par exemple, la fonction échoue si hWnd est un handle de fenêtre non valide ou lpMsg est un pointeur non valide. Pour obtenir des informations d’erreur étendues, appelez GetLastError.
Étant donné que la valeur de retour peut être différente de zéro, zéro ou -1, évitez le code comme suit :
while (GetMessage( lpMsg, hWnd, 0, 0)) ...
La possibilité d’une valeur de retour -1 dans le cas où hWnd est un paramètre non valide (par exemple, faire référence à une fenêtre qui a déjà été détruite) signifie que ce code peut entraîner des erreurs d’application irrécupérables. Utilisez plutôt du code comme suit :
BOOL bRet;
while( (bRet = GetMessage( &msg, hWnd, 0, 0 )) != 0)
{
if (bRet == -1)
{
// handle the error and possibly exit
}
else
{
TranslateMessage(&msg);
DispatchMessage(&msg);
}
}
Remarques
Une application utilise généralement la valeur de retour pour déterminer s’il faut mettre fin à la boucle de message principale et quitter le programme.
La fonction
Notez que GetMessage 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 remet des messages en attente, non mis en file d’attente, c’est-à-dire des messages envoyés aux fenêtres appartenant au thread appelant à l’aide du
- Messages envoyés
- Messages publiés
- Messages d’entrée (matériel) et événements internes système
- Messages envoyés (à nouveau)
- messages WM_PAINT
- messages WM_TIMER
GetMessage ne supprime pas les messages WM_PAINT de la file d’attente. Les messages restent dans la file d’attente jusqu’à ce qu’ils soient traités.
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 z, emplacement, taille et 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 réellement. Lorsqu’il est en mode débogueur, le système ne génère pas de fenêtre fantôme.
virtualisation d'ppp
Cette API ne participe pas à la virtualisation DPI. La sortie est en 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 Création d’une boucle de message.
Note
L’en-tête winuser.h définit GetMessage comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | winuser.h (include 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
conceptuelle
messages et files d’attente de messages
de référence