PostThreadMessageA, fonction (winuser.h)

Article
11/20/2024

Publie un message dans la file d’attente de messages du thread spécifié. Elle retourne sans attendre que le thread traite le message.

Syntaxe

BOOL PostThreadMessageA(
  [in] DWORD  idThread,
  [in] UINT   Msg,
  [in] WPARAM wParam,
  [in] LPARAM lParam
);

Paramètres

[in] idThread

Type : DWORD

Identificateur du thread dans lequel le message doit être publié.

La fonction échoue si le thread spécifié n’a pas de file d’attente de messages. Le système crée la file d’attente de messages d’un thread lorsque le thread effectue son premier appel à l’une des fonctions Utilisateur ou GDI. Pour plus d’informations, consultez la section Remarques.

La publication de messages est soumise à l’UIPI. Le thread d’un processus peut publier des messages uniquement dans les files d’attente de messages publiées des threads dans les processus de niveau d’intégrité inférieur ou égal.

Ce thread doit avoir le privilège SE_TCB_NAME de publier un message sur un thread qui appartient à un processus avec le même identificateur local unique (LUID), mais se trouve dans un autre bureau. Sinon, la fonction échoue et retourne ERROR_INVALID_THREAD_ID.

Ce thread doit appartenir au même bureau que le thread appelant ou à un processus avec le même LUID. Sinon, la fonction échoue et retourne ERROR_INVALID_THREAD_ID.

[in] Msg

Type : uiNT

Type de message à publier.

[in] wParam

Type : WPARAM

Informations supplémentaires spécifiques aux messages.

[in] lParam

Type : LPARAM

Informations supplémentaires spécifiques aux messages.

Valeur de retour

Type : BOOL

Si la fonction réussit, la valeur de retour est différente de zéro.

Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations d’erreur étendues, appelez GetLastError. GetLastError retourne ERROR_INVALID_THREAD_ID si idThread n’est pas un identificateur de thread valide ou si le thread spécifié par idThread n’a pas de file d’attente de messages. GetLastError retourne ERROR_NOT_ENOUGH_QUOTA lorsque la limite de message est atteinte.

Remarques

Lorsqu’un message est bloqué par l’UIPI la dernière erreur, récupérée avec GetLastError, est définie sur 5 (accès refusé).

Le thread sur lequel le message est publié doit avoir créé une file d’attente de messages, ou bien l’appel à PostThreadMessage échoue. Utilisez la méthode suivante pour gérer cette situation.

Créez un objet d’événement, puis créez le thread.
Utilisez la fonction WaitForSingleObject pour attendre que l’événement soit défini sur l’état signalé avant d’appeler PostThreadMessage.
Dans le thread sur lequel le message sera publié, appelez peekMessage comme indiqué ici pour forcer le système à créer la file d’attente de messages.
PeekMessage(&msg, NULL, WM_USER, WM_USER, PM_NOREMOVE)
Définissez l’événement pour indiquer que le thread est prêt à recevoir des messages publiés.

Le thread dans lequel le message est publié récupère le message en appelant la fonction GetMessage ou fonction PeekMessage. Le membre du MSG retourné est NULL .

Les messages publiés par PostThreadMessage ne sont pas associés à une fenêtre. En règle générale, les messages qui ne sont pas associés à une fenêtre ne peuvent pas être distribués par la fonction DispatchMessage. Par conséquent, si le thread du destinataire se trouve dans une boucle modale (comme utilisé par MessageBox ou DialogBox), les messages seront perdus. Pour intercepter les messages de thread dans une boucle modale, utilisez un hook spécifique au thread.

Le système effectue uniquement le marshaling pour les messages système (ceux de la plage 0 à (WM_USER-1)). Pour envoyer d’autres messages (ces >= WM_USER) à un autre processus, vous devez effectuer un marshaling personnalisé.

Il existe une limite de 10 000 messages publiés par file d’attente de messages. Cette limite doit être suffisamment grande. Si votre application dépasse la limite, elle doit être repensée pour éviter de consommer tant de ressources système. Pour ajuster cette limite, modifiez la clé de Registre suivante.

HKEY_LOCAL_MACHINE
   SOFTWARE
      Microsoft
         Windows NT
            CurrentVersion
               Windows
                  USERPostMessageLimit

La valeur minimale acceptable est 4 000.

Note

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