Fonction WaitForSingleObject (synchapi.h)
Attend que l’objet spécifié soit à l’état signalé ou que l’intervalle de délai d’attente s’écoule.
Pour entrer un état d’attente pouvant être alerté, utilisez la fonction WaitForSingleObjectEx . Pour attendre plusieurs objets, utilisez WaitForMultipleObjects.
Syntaxe
DWORD WaitForSingleObject(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds
);
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é ou que l’intervalle s’écoule. Si dwMillisecondes est égal à zéro, la fonction n’entre pas en état d’attente si l’objet n’est pas signalé ; il retourne toujours immédiatement. Si dwMillisecondes est INFINITE, la fonction retourne uniquement lorsque l’objet est signalé.
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.
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 |
|---|---|
|
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 l’arrêt du thread propriétaire. La propriété de l’objet mutex est accordée au thread appelant et l’état 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’état de l’objet spécifié est signalé. |
|
L’intervalle de délai d’attente s’est écoulé et l’état de l’objet n’est pas signé. |
|
La fonction a échoué. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError. |
Remarques
La fonction WaitForSingleObject vérifie l’état actuel de l’objet spécifié. Si l’état de l’objet n’est pas signé, le thread appelant entre dans l’état d’attente jusqu’à ce que l’objet soit signalé ou que l’intervalle de délai d’expiration 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’objets sémaphores est réduit d’un.
La fonction WaitForSingleObject peut attendre les objets suivants :
- Notification de modification
- Entrée console
- Événement
- Notification des ressources de mémoire
- Mutex
- Processus
- Semaphore
- Thread
- Minuteur pouvant être attendu
Exemples
Pour obtenir un exemple, consultez Utilisation d’objets Mutex.
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 |