Fonction MsgWaitForMultipleObjects (winuser.h)
Attend qu’un ou tous les objets spécifiés soient à l’état signalé ou que l’intervalle de délai d’attente s’écoule. Les objets peuvent inclure des objets d’événement d’entrée, que vous spécifiez à l’aide du paramètre dwWakeMask .
Pour entrer un état d’attente pouvant être alerté, utilisez la fonction MsgWaitForMultipleObjectsEx .
Syntaxe
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
Paramètres
[in] nCount
Nombre de handles d’objet dans le tableau pointé vers pHandles. Le nombre maximal de handles d’objet est MAXIMUM_WAIT_OBJECTS moins un. Si ce paramètre a la valeur zéro, la fonction attend uniquement un événement d’entrée.
[in] pHandles
Tableau de handles d’objet. Pour obtenir la liste des types d’objets dont les handles peuvent être spécifiés, consultez la section Remarques suivante. Le tableau peut contenir des handles d’objets de différents types. Il ne peut pas contenir plusieurs copies du même handle.
Si l’un de ces handles est fermé alors que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.
Les handles doivent avoir le droit d’accès SYNCHRONIZE . Pour plus d’informations, consultez Droits d’accès standard.
[in] fWaitAll
Si ce paramètre a la valeur TRUE, la fonction retourne lorsque les états de tous les objets du tableau pHandles ont été signalés et qu’un événement d’entrée a été reçu. Si ce paramètre a la valeur FALSE, la fonction retourne lorsque l’état de l’un des objets est défini sur signalé ou qu’un événement d’entrée a été reçu. Dans ce cas, la valeur de retour indique l’objet dont l’état a provoqué le retour de la fonction.
[in] dwMilliseconds
Intervalle de délai d’attente, en millisecondes. Si une valeur différente de zéro est spécifiée, la fonction attend que les objets spécifiés soient signalés ou que l’intervalle s’écoule. Si dwMillisecondes est égal à zéro, la fonction n’entre pas en état d’attente si les objets spécifiés ne sont pas signalés ; il retourne toujours immédiatement. Si dwMillisecondes est INFINITE, la fonction retourne uniquement lorsque les objets spécifiés sont signalés.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 et Windows Server 2008 R2 : La valeur dwMilliseconds inclut le temps passé dans des états de faible puissance. Par exemple, le délai d’attente continue de compter pendant que l’ordinateur est en veille.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 et Windows Server 2016 : la valeur dwMilliseconds n’inclut pas le temps passé en basse puissance États. Par exemple, le délai d’attente ne continue pas à compter pendant que l’ordinateur est en veille.
[in] dwWakeMask
Types d’entrée pour lesquels un handle d’objet d’événement d’entrée sera ajouté au tableau de handles d’objet. Ce paramètre peut être n’importe quelle combinaison des valeurs répertoriées dans le paramètre d’indicateursGetQueueStatus.
Valeur retournée
Si la fonction réussit, la valeur de retour indique l’événement qui a provoqué le retour de la fonction. Il peut avoir l’une des valeurs suivantes. (Notez que WAIT_OBJECT_0 est défini sur 0 et WAIT_ABANDONED_0 est défini sur 0x00000080L.)
| Code/valeur de retour | Description |
|---|---|
|
Si bWaitAll a la valeur TRUE, une valeur de retour dans la plage spécifiée indique que l’état de tous les objets spécifiés est signalé. Si bWaitAll a la valeur FALSE, la valeur de retour moins WAIT_OBJECT_0 indique l’index de tableau pHandles de l’objet qui a satisfait l’attente. |
|
Une nouvelle entrée du type spécifié dans le paramètre dwWakeMask est disponible dans la file d’attente d’entrée du thread. Les fonctions telles que PeekMessage, GetMessage et WaitMessage marquent les messages de la file d’attente comme d’anciens messages. Par conséquent, après avoir appelé l’une de ces fonctions, un appel ultérieur à MsgWaitForMultipleObjects ne retourne pas tant que la nouvelle entrée du type spécifié n’est pas arrivée.
Cette valeur est également retournée lors de l’occurrence d’un événement système qui nécessite l’action du thread, comme l’activation au premier plan. Par conséquent, MsgWaitForMultipleObjects peut retourner même si aucune entrée appropriée n’est disponible et même si dwWakeMask a la valeur 0. Si cela se produit, appelez GetMessage ou PeekMessage pour traiter l’événement système avant de réessayer l’appel à MsgWaitForMultipleObjects . |
|
Si bWaitAll a la valeur TRUE, une valeur de retour dans la plage spécifiée indique que l’état de tous les objets spécifiés est signalé et qu’au moins l’un des objets est un objet mutex abandonné. Si bWaitAll a la valeur FALSE, la valeur de retour moins WAIT_ABANDONED_0 indique l’index de tableau pHandles d’un objet mutex abandonné qui a satisfait l’attente. La propriété de l’objet mutex est accordée au thread appelant et le mutex est défini sur non signé.
Si le mutex protégeait les informations d’état persistantes, vous devez vérifier sa cohérence. |
|
L’intervalle de délai d’attente s’est écoulé et les conditions spécifiées par les paramètres bWaitAll et dwWakeMask n’ont pas été satisfaites. |
|
La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. |
Remarques
La fonction MsgWaitForMultipleObjects détermine si les critères d’attente ont été remplis. Si les critères n’ont pas été remplis, le thread appelant entre dans l’état d’attente jusqu’à ce que les conditions des critères d’attente soient remplies ou que l’intervalle de délai d’attente ne soit écoulé.
Lorsque bWaitAll a la valeur TRUE, la fonction ne modifie pas les états des objets spécifiés tant que les états de tous les objets n’ont pas été définis sur signalés. Par exemple, un mutex peut être signalé, mais le thread n’obtient pas la propriété tant que les états des autres objets n’ont pas également été définis sur signalés. En attendant, un autre thread peut obtenir la propriété du mutex, ce qui définit son état sur non signé.
Lorsque bWaitAll a la valeur TRUE, l’attente de la fonction n’est terminée que lorsque les états de tous les objets ont été définis sur signalés et qu’un événement d’entrée a été reçu. Par conséquent, la définition de bWaitAll sur TRUE empêche le traitement de l’entrée tant que l’état de tous les objets du tableau pHandles n’a pas été défini sur signal. Pour cette raison, si vous définissez bWaitAll sur TRUE, vous devez utiliser une valeur de court délai d’attente en dwMilliseconds. Si vous avez un thread qui crée des fenêtres qui attendent tous les objets du tableau pHandles , y compris les événements d’entrée spécifiés par dwWakeMask, sans intervalle de délai d’expiration, le système se bloquera. En effet, les threads qui créent des fenêtres doivent traiter les messages. DDE envoie un message à toutes les fenêtres du système. Par conséquent, si un thread crée des fenêtres, ne définissez pas le paramètre bWaitAll sur TRUE dans les appels à MsgWaitForMultipleObjects effectués à partir de ce thread.
Lorsque bWaitAll a la valeur FALSE, cette fonction vérifie les handles dans le tableau dans l’ordre commençant par l’index 0, jusqu’à ce que l’un des objets soit signalé. Si plusieurs objets sont signalés, la fonction retourne l’index du premier handle du tableau dont l’objet a été signalé.
MsgWaitForMultipleObjects ne retourne pas s’il existe une entrée non lus du type spécifié dans la file d’attente de messages après que le thread a appelé une fonction pour vérifier la file d’attente. En effet, les fonctions telles que PeekMessage, GetMessage, GetQueueStatus et WaitMessage vérifient la file d’attente, puis modifient les informations d’état de la file d’attente afin que l’entrée ne soit plus considérée comme nouvelle. Un appel suivant à MsgWaitForMultipleObjects ne retourne pas tant que la nouvelle entrée du type spécifié n’est pas arrivée. L’entrée non lus existante (reçue avant la dernière fois que le thread a vérifié la file d’attente) est ignorée.
La fonction modifie l’état de certains types d’objets de synchronisation. La modification se produit uniquement pour l’objet ou les objets dont l’état signalé a provoqué le retour de la fonction. Par exemple, le nombre d’objets sémaphores est réduit d’un. Pour plus d’informations, consultez la documentation relative aux objets de synchronisation individuels.
La fonction MsgWaitForMultipleObjects peut spécifier des handles de l’un des types d’objets suivants dans le tableau pHandles :
- Notification de modification
- Entrée console
- Événement
- Notification des ressources de mémoire
- Mutex
- Process
- Semaphore
- Thread
- Minuteur pouvant être attendu
Spécifications
| Client minimal pris en charge | Windows XP [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | winuser.h (inclure Windows.h) |
| Bibliothèque | User32.lib |
| DLL | User32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour