Fonction WaitForSingleObjectEx (synchapi.h)

  • Article

Attend que l’objet spécifié soit à 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’attente s’écoule.

Pour attendre plusieurs objets, utilisez WaitForMultipleObjectsEx.

Syntaxe

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

Paramètres

[in] hHandle

Handle de l’objet . Pour obtenir la liste des types d’objets dont les handles peuvent être spécifiés, consultez la section Remarques suivante.

Si ce handle est fermé alors que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.

Le handle doit 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 l’objet soit signalé, 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 dwMilliseconds est égal à zéro, la fonction n’entre pas en état d’attente si les critères ne sont pas remplis ; elle retourne toujours immédiatement. Si dwMilliseconds a la valeur INFINITE, la fonction retourne uniquement lorsque l’objet est signalé ou qu’une routine d’achèvement d’E/S ou qu’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] bAlertable

Si ce paramètre a la valeur TRUE et que le thread est dans l’état d’attente, la fonction retourne lorsque le système met en file d’attente une routine d’achèvement d’E/S ou APC, et que le thread exécute la routine ou la fonction. Sinon, la fonction ne retourne pas et la routine d’achèvement ou la fonction APC n’est pas exécutée.

Une routine d’achèvement est mise en file d’attente lorsque la fonction ReadFileEx ou WriteFileEx dans laquelle elle a été spécifiée s’est terminée. La fonction d’attente retourne et la routine d’achèvement est appelée uniquement si bAlertable a la valeur TRUE et si le thread appelant est le thread qui a lancé l’opération de lecture ou d’écriture. Un APC est mis en file d’attente quand vous appelez QueueUserAPC.

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.

Code/valeur de retour Description
WAIT_ABANDONED
0x00000080L
 L’objet spécifié est un objet mutex qui n’a pas été libéré par le thread qui possédait l’objet mutex avant la fin du thread propriétaire. 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 l’case activée à des fins de cohérence.
WAIT_IO_COMPLETION
0x000000C0L
 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.
WAIT_OBJECT_0
0x00000000L
 L’état de l’objet spécifié est signalé.
WAIT_TIMEOUT
0x00000102L
 L’intervalle de délai d’attente s’est écoulé et l’état de l’objet n’est pas signé.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La fonction WaitForSingleObjectEx détermine si les critères d’attente ont été remplis. Si les critères n’ont pas été remplis, le thread appelant passe à 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.

La fonction modifie l’état de certains types d’objets de synchronisation. La modification se produit uniquement pour l’objet dont l’état signalé a provoqué le retour de la fonction. Par exemple, le nombre d’un objet sémaphore est réduit d’un.

La fonction WaitForSingleObjectEx peut attendre les objets suivants :

  • Notification de modification
  • Entrée de console
  • Événement
  • Notification de ressource mémoire
  • Mutex
  • Processus
  • Semaphore
  • Thread
  • Minuteur d’attente
Soyez prudent lorsque vous appelez les fonctions d’attente et le code qui créent directement ou indirectement des fenêtres. Si un thread crée des fenêtres, il doit traiter les messages. Les diffusions de messages sont envoyées à toutes les fenêtres du système. Un thread qui utilise une fonction d’attente sans intervalle de délai d’attente peut entraîner l’interblocage du système. Deux exemples de code qui créent indirectement des fenêtres sont DDE et la fonction CoInitialize . Par conséquent, si vous avez un thread qui crée des fenêtres, utilisez MsgWaitForMultipleObjects ou MsgWaitForMultipleObjectsEx, plutôt que WaitForSingleObjectEx.

Exemples

Pour obtenir un exemple, consultez Serveur de canal nommé à l’aide de routines d’achèvement.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau | applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête synchapi.h (inclure Windows.h sur Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

Fonctions de synchronisation

Fonctions d’attente