Funzione WaitForSingleObjectEx (synchapi.h)
Attende fino a quando l'oggetto specificato non si trova nello stato segnalato, una routine di completamento I/O o una chiamata di routine asincrona (APC) viene accodata al thread o l'intervallo di timeout trascorso.
Per attendere più oggetti, usare WaitForMultipleObjectsEx.
Sintassi
DWORD WaitForSingleObjectEx(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parametri
[in] hHandle
Handle per l'oggetto. Per un elenco dei tipi di oggetto i cui handle possono essere specificati, vedere la sezione Osservazioni seguente.
Se questo handle viene chiuso mentre l'attesa è ancora in sospeso, il comportamento della funzione non è definito.
L'handle deve avere il diritto di accesso SYNC . Per altre informazioni, vedere Diritti di accesso standard.
[in] dwMilliseconds
Intervallo di timeout, in millisecondi. Se viene specificato un valore diverso da zero, la funzione attende fino a quando l'oggetto non viene segnalato, una routine di completamento di I/O o viene accodata o l'intervallo trascorso. Se dwMilliseconds è zero, la funzione non immette uno stato di attesa se i criteri non vengono soddisfatti; restituisce sempre immediatamente. Se dwMilliseconds è INFINITE, la funzione restituirà solo quando l'oggetto viene segnalato o una routine di completamento di I/O o viene accodata.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include tempo trascorso in stati di bassa potenza. Ad esempio, il timeout mantiene il conteggio mentre il computer è inattivo.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: il valore dwMilliseconds non include tempo trascorso in bassa potenza Stati. Ad esempio, il timeout non mantiene il conteggio mentre il computer è inattivo.
[in] bAlertable
Se questo parametro è TRUE e il thread si trova nello stato di attesa, la funzione restituisce quando il sistema accoda una routine di completamento I/O o APC e il thread esegue la routine o la funzione. In caso contrario, la funzione non restituisce e la routine di completamento o la funzione APC non viene eseguita.
Una routine di completamento viene accodata quando è stata completata la funzione ReadFileEx o WriteFileEx in cui è stato specificato. La funzione di attesa restituisce e la routine di completamento viene chiamata solo se bAlertable è TRUE e il thread chiamante è il thread che ha avviato l'operazione di lettura o scrittura. Un APC viene accodato quando si chiama QueueUserAPC.
Valore restituito
Se la funzione ha esito positivo, il valore restituito indica l'evento che ha causato la restituzione della funzione. Può essere uno dei valori seguenti.
Codice/valore restituito | Descrizione |
---|---|
|
L'oggetto specificato è un oggetto mutex che non è stato rilasciato dal thread che appartiene all'oggetto mutex prima della chiusura del thread proprietario. La proprietà dell'oggetto mutex viene concessa al thread chiamante e il mutex è impostato su nonsignaled.
Se il mutex proteggeva le informazioni sullo stato persistenti, è necessario controllarlo per la coerenza. |
|
L'attesa è stata terminata da una o più chiamate asincrone in modalità utente (APC) accodate al thread. |
|
Lo stato dell'oggetto specificato viene segnalato. |
|
Intervallo di timeout trascorso e lo stato dell'oggetto non è assegnato. |
|
La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError. |
Commenti
La funzione WaitForSingleObjectEx determina se sono stati soddisfatti i criteri di attesa. Se i criteri non sono stati soddisfatti, il thread chiamante entra nello stato di attesa fino a quando non sono state soddisfatte le condizioni dei criteri di attesa o l'intervallo di timeout trascorso.
La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica si verifica solo per l'oggetto il cui stato segnalato ha causato la restituzione della funzione. Ad esempio, il conteggio di un oggetto semaforo è ridotto di uno.
La funzione WaitForSingleObjectEx può attendere gli oggetti seguenti:
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaphore
- Thread
- Timer attendebile
Esempio
Per un esempio, vedere Named Pipe Server Using Completion Routines( Routine di completamento).
Requisiti
Requisito | Valore |
---|---|
Client minimo supportato | Windows XP [app desktop | App UWP] |
Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
Piattaforma di destinazione | Windows |
Intestazione | synchapi.h (includere Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
Libreria | Kernel32.lib |
DLL | Kernel32.dll |