Funzione WaitForSingleObjectEx (synchapi.h)

  • Articolo

Attende fino a quando l'oggetto specificato non è nello stato segnalato, una routine di completamento I/O o una chiamata di procedura 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 SYNCHRONIZE . Per altre informazioni, vedere Standard Access Rights.

[in] dwMilliseconds

Intervallo di timeout, espresso in millisecondi. Se viene specificato un valore diverso da zero, la funzione attende finché l'oggetto non viene segnalato, viene accodata una routine di completamento I/O o APC 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 viene accodata una routine di completamento I/O o APC.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include il tempo impiegato in stati a basso consumo. Ad esempio, il timeout continua a contare mentre il computer è in stato di sospensione.

Windows 8 e versioni successive, Windows Server 2012 e versioni successive: Il valore dwMilliseconds non include il tempo impiegato in stati a basso consumo. Ad esempio, il timeout non continua a contare mentre il computer è in stato di sospensione.

[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 la funzione ReadFileEx o WriteFileEx in cui è stata specificata è stata completata. La funzione wait restituisce e la routine di completamento viene chiamata solo se bAlertable è TRUEe 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
WAIT_ABANDONED
0x00000080L
 L'oggetto specificato è un oggetto mutex che non è stato rilasciato dal thread che appartiene all'oggetto mutex prima che il thread proprietario venga terminato. La proprietà dell'oggetto mutex viene concessa al thread chiamante e il mutex è impostato su non firmato.

Se il mutex proteggeva le informazioni sullo stato permanenti, è necessario verificarne la coerenza.
WAIT_IO_COMPLETION
0x000000C0L
 L'attesa è stata terminata da una o più chiamate di routine asincrone in coda al thread.
WAIT_OBJECT_0
0x00000000L
 Lo stato dell'oggetto specificato viene segnalato.
WAIT_TIMEOUT
0x00000102L
 Intervallo di timeout trascorso e lo stato dell'oggetto non è firmato.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 La funzione non è riuscita. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

La funzione WaitForSingleObjectEx determina se i criteri di attesa sono stati soddisfatti. 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 scade.

La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica viene eseguita solo per l'oggetto il cui stato segnalato ha causato la restituzione della funzione. Ad esempio, il conteggio di un oggetto semaforo viene 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
  • Semaforo
  • Filo
  • Timer waitable
Prestare attenzione quando si chiamano le funzioni di attesa e il codice che crea direttamente o indirettamente finestre. Se un thread crea finestre, deve elaborare i messaggi. Le trasmissioni di messaggi vengono inviate a tutte le finestre del sistema. Un thread che usa una funzione di attesa senza intervallo di timeout può causare il deadlock del sistema. Due esempi di codice che creano indirettamente finestre sono DDE e la funzione CoInitialize. Pertanto, se si dispone di un thread che crea finestre, usare MsgWaitForMultipleObjects o MsgWaitForMultipleObjectsEx, anziché WaitForSingleObjectEx.

Esempi

Per un esempio, vedere server named pipe tramite routine di completamento.

Fabbisogno

Requisito Valore
client minimo supportato Windows XP [app desktop | App UWP]
server minimo supportato Windows Server 2003 [app desktop | App UWP]
piattaforma di destinazione Finestre
intestazione synchapi.h (include Windows.h in Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2)
libreria Kernel32.lib
dll Kernel32.dll

Vedere anche

funzioni di sincronizzazione

funzioni di attesa