WaitForSingleObjectEx, fonction (synchapi.h)
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, soit que l’intervalle de délai d’attente s’écoule.
Pour attendre plusieurs objets, utilisez l'WaitForMultipleObjectsEx.
Syntaxe
DWORD WaitForSingleObjectEx(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Paramètres
[in] hHandle
Handle vers 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é pendant que l’attente est toujours en attente, le comportement de la fonction n’est pas défini.
Le handle doit disposer du droit d’accès SYNCHRONIZE. Pour plus d’informations, consultez Standard Access Rights.
[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 d’APC soit mise en file d’attente ou que l’intervalle s’écoule. Si dwMilliseconds est égal à zéro, la fonction n’entre pas dans un état d’attente si les critères ne sont pas remplis ; elle retourne toujours immédiatement. Si dwMilliseconds est infinite, la fonction retourne uniquement lorsque l’objet est signalé ou qu’une routine d’achèvement d’E/S ou d’APC est mise 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 à 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] bAlertable
Si ce paramètre est 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 d’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 a été terminée. La fonction d’attente retourne et la routine d’achèvement est appelée uniquement si bAlertable est TRUE, et 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 lorsque vous appelez QueueUserAPC.
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.
| Retourner le code/la valeur | 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 le mutex est défini sur non signé.
Si le mutex protège les informations d’état persistant, vous devez vérifier la 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’état de l’objet spécifié est signalé. |
|
Intervalle de délai d’attente écoulé, et l’état de l’objet n’est pas signé. |
|
La fonction a échoué. Pour obtenir des informations d’erreur étendues, 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 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.
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 diminué 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
- Sémaphore
- Fil
- Minuteur pouvant être attendu
Exemples
Pour obtenir un exemple, consultez serveur de canal nommé à l’aide de routines d’achèvement.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau | Applications UWP] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau | Applications UWP] |
| plateforme cible | Windows |
| d’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 |