Fonction GetMessage (winuser.h)

Article
03/13/2024

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 récupération.

GetMessage fonctionne comme PeekMessage, cependant, GetMessage bloque jusqu’à ce qu’un message soit publié avant le retour.

Syntaxe

BOOL GetMessage(
  [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 les informations de message de la file d’attente de messages du thread.

[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 actif.

Si hWnd a la valeur NULL, GetMessage récupère les messages pour n’importe quelle fenêtre qui appartient au thread actif, ainsi que tous les messages de la file d’attente de messages du thread actif 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, GetMessage récupère uniquement les messages de la file d’attente de messages du thread actif dont la valeur hwnd est NULL, c’est-à-dire les messages de thread tels qu’ils sont publiés par PostMessage (lorsque le paramètre hWnd est NULL) ou PostThreadMessage.

[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 souris.

Utilisez WM_INPUT ici et dans wMsgFilterMax pour spécifier uniquement les messages WM_INPUT .

Si wMsgFilterMin et wMsgFilterMax sont tous deux 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 du 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 tous deux zéro, GetMessage retourne tous les messages disponibles (autrement dit, aucun filtrage de plage n’est effectué).

Valeur retournée

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 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 si lpMsg est un pointeur non valide. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Étant donné que la valeur de retour peut être différente de zéro, zéro ou -1, évitez le code suivant :

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, la référence à une fenêtre qui a déjà été détruite) signifie qu’un tel code peut entraîner des erreurs d’application irrécupérables. Utilisez plutôt le code suivant :

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 main et quitter le programme.

La fonction GetMessage 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 bas dans les paramètres wMsgFilterMin et wMsgFilterMax ; le mot haut est réservé au système.

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

Au cours de cet appel, le système remet les messages en attente, 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 .

GetMessage ne supprime pas WM_PAINT messages 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 les mêmes attributs d’ordre z, d’emplacement, de taille et de visuel. 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. En mode débogueur, le système ne génère pas de fenêtre fantôme.

Virtualisation DPI

Cette API ne participe pas à la virtualisation DPI. La sortie se trouve 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 Création d’une boucle de message.

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)