MsgWaitForMultipleObjectsEx, fonction (winuser.h)
Attend qu’un ou tous les objets spécifiés soient à l’état signalé, qu’une routine d’achèvement d’E/S ou un appel de procédure asynchrone (APC) soit mis en file d’attente vers le thread, ou que l’intervalle de délai d’expiration s’écoule. Le tableau d’objets peut inclure des objets d’événement d’entrée que vous spécifiez à l’aide du paramètre dwWakeMask .
Syntaxe
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
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 vous pouvez spécifier les handles, consultez la section Remarques plus loin dans cette rubrique. Le tableau peut contenir des handles pour plusieurs types d’objets. 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] 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, qu’une routine d’achèvement d’E/S ou un APC soit mis en file d’attente, ou que l’intervalle s’écoule. Si dwMillisecondes est égal à zéro, la fonction n’entre pas en état d’attente si les critères ne sont pas remplis ; il retourne toujours immédiatement. Si dwMillisecondes est INFINITE, la fonction ne retourne que lorsque les objets spécifiés sont signalés ou qu’une routine d’achèvement d’E/S ou quand APC est mis en file d’attente.
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 les états de faible consommation d’énergie. Par exemple, le décompte du délai d’expiration continue 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é dans les états de faible consommation d’énergie. Par exemple, le décompte du délai d’expiration est arrêté quand 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.
[in] dwFlags
Type d’attente. Ce paramètre peut prendre une ou plusieurs des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
La fonction retourne quand l’un des objets est signalé. La valeur de retour indique l’objet dont l’état a provoqué le retour de la fonction. |
|
La fonction retourne également si un APC a été mis en file d’attente vers le thread avec QueueUserAPC alors que le thread est en attente. |
|
La fonction retourne si une entrée existe pour la file d’attente, même si l’entrée a été vue (mais pas supprimée) à l’aide d’un appel à une autre fonction, telle que PeekMessage. |
|
La fonction retourne lorsque tous les objets du tableau pHandles sont signalés et qu’un événement d’entrée a été reçu en même temps. |
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 l’indicateur MWMO_WAITALL est utilisé, une valeur de retour dans la plage spécifiée indique que l’état de tous les objets spécifiés est signalé. Sinon, la valeur de retour moins WAIT_OBJECT_0 indique l’index de tableau pHandles de l’objet qui a provoqué le retour de la fonction. |
|
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, GetQueueStatus 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 à MsgWaitForMultipleObjectsEx 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, MsgWaitForMultipleObjectsEx peut retourner même si aucune entrée appropriée n’est disponible et même si dwWakeMask est défini sur 0. Si cela se produit, appelez GetMessage ou PeekMessage pour traiter l’événement système avant d’essayer à nouveau l’appel à MsgWaitForMultipleObjectsEx . |
|
Si l’indicateur MWMO_WAITALL est utilisé, 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é. Sinon, la valeur de retour moins WAIT_ABANDONED_0 indique l’index de tableau pHandles d’un objet mutex abandonné qui a provoqué le retour de la fonction. 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 les case activée à des fins de cohérence. |
|
L’attente a été terminée par un ou plusieurs appels de procédure asynchrone en mode utilisateur (APC) mis en file d’attente vers le thread. |
|
L’intervalle de délai d’attente s’est écoulé, mais les conditions spécifiées par les paramètres dwFlags et dwWakeMask n’ont pas été remplies. |
|
La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. |
Remarques
La fonction MsgWaitForMultipleObjectsEx détermine si les conditions spécifiées par dwWakeMask et dwFlags ont été remplies. Si les conditions n’ont pas été remplies, 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 s’écoule.
Lorsque dwFlags est égal à zéro, 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é.
MsgWaitForMultipleObjectsEx 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 case activée la file d’attente, sauf si vous utilisez l’indicateur MWMO_INPUTAVAILABLE. En effet, des fonctions telles que PeekMessage, GetMessage, GetQueueStatus et WaitMessage case activée 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 ultérieur à MsgWaitForMultipleObjectsEx ne retourne pas tant que la nouvelle entrée du type spécifié n’est pas arrivée, sauf si vous utilisez l’indicateur MWMO_INPUTAVAILABLE . Si cet indicateur n’est pas utilisé, l’entrée non lus existante (reçue avant la dernière vérification de la file d’attente par le thread) 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 système réduit d’un seul le nombre d’objets sémaphores. Pour plus d’informations, consultez la documentation relative aux objets de synchronisation individuels.
La fonction MsgWaitForMultipleObjectsEx 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
- Processus
- Semaphore
- Thread
- Minuteur pouvant être attendu
Configuration requise
| Condition requise | Valeur |
|---|---|
| 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