GetMessageW, fonction (winuser.h)

Article
06/08/2023

Récupère un message 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.

Contrairement à GetMessage, la fonction PeekMessage n’attend pas qu’un message soit publié avant de revenir.

Syntaxe

BOOL GetMessageW(
  [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 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, GetMessage récupère les messages pour toutes les fenêtres qui appartiennent au thread actuel et 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, GetMessage 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 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 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 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 (comme 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 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 faible 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.

Pendant cet appel, le système remet des messages en attente et non mis en file d’attente, c’est-à-dire des 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 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. En mode débogueur, 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 Création d’une boucle de message.

Notes

L’en-tête winuser.h définit GetMessage 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)