MsgWaitForMultipleObjects, fonction (winuser.h)

Attend qu’un ou tous les objets spécifiés soient dans 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 alertable, 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é par 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 peut ne pas contenir plusieurs copies du même handle.

Si l’un de ces handles est fermé pendant que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.

Les handles doivent disposer du droit d’accès SYNCHRONIZE. Pour plus d’informations, consultez Standard Access Rights.

[in] fWaitAll

Si ce paramètre est TRUE, la fonction retourne lorsque les états de tous les objets du tableau pHandles ont été définis pour signaler et qu’un événement d’entrée a été reçu. Si ce paramètre est FALSE, la fonction retourne lorsque l’état d’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 dwMilliseconds est égal à zéro, la fonction n’entre pas dans un état d’attente si les objets spécifiés ne sont pas signalés ; elle retourne toujours immédiatement. Si dwMilliseconds est INFINITE, la fonction ne retourne que 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 les états à faible alimentation. Par exemple, le délai d’attente ne cesse de compter pendant que l’ordinateur est endormi.

Windows 8 et versions ultérieures, Windows Server 2012 et versions ultérieures : La valeur dwMilliseconds n’inclut pas le temps passé dans les états à faible alimentation. Par exemple, le délai d’expiration ne continue pas à compter pendant que l’ordinateur est endormi.

[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 GetQueueStatusindicateurs paramètre.

Valeur de retour

Si la fonction réussit, la valeur de retour indique l’événement qui a provoqué le retour de la fonction. Il peut s’agir de l’une des valeurs suivantes. (Notez que WAIT_OBJECT_0 est défini comme 0 et WAIT_ABANDONED_0 est défini comme 0x00000080L.)

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 aient été remplies ou que l’intervalle de délai d’attente s’écoule.

Lorsque bWaitAll est 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 comme 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 est TRUE, l’attente de la fonction est terminée uniquement lorsque les états de tous les objets ont été définis pour signaler et qu’un événement d’entrée a été reçu. Par conséquent, définir bWaitAll sur TRUE empêche le traitement de l’entrée jusqu’à ce que l’état de tous les objets dans le tableau pHandles ait été défini sur signalé. Pour cette raison, si vous définissez bWaitAll sur TRUE, vous devez utiliser une valeur de délai d’attente courte dans dwMilliseconds. Si vous avez un thread qui crée des fenêtres en attente de 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 interbloque. Cela est dû au fait que 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ée à partir de ce thread.

Lorsque bWaitAll est FALSE, cette fonction vérifie les handles du tableau dans l’ordre commençant par l’index 0, jusqu’à ce qu’un des objets soit signalé. Si plusieurs objets deviennent signalés, la fonction retourne l’index du premier handle dans le tableau dont l’objet a été signalé.

MsgWaitForMultipleObjects ne retourne pas s’il existe une entrée non lue du type spécifié dans la file d’attente de messages une fois que le thread a appelé une fonction pour vérifier la file d’attente. Cela est dû au fait que les fonctions telles que PeekMessage, GetMessage, GetQueueStatuset WaitMessage vérifier la file d’attente, puis modifier 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 à MsgWaitForMultipleObjects ne retourne pas tant que la nouvelle entrée du type spécifié n’arrive pas. 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’un objet sémaphore est diminué 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 de console
• Événement
• Notification de ressource mémoire
• Mutex
• Processus
• Sémaphore
• Fil
• Minuteur pouvant être attendu

Exigences

Voir aussi

MsgWaitForMultipleObjectsEx

fonctions de synchronisation

Fonctions d’attente