Funzione MsgWaitForMultipleObjectsEx (winuser.h)
Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato, una routine di completamento I/O o una chiamata asincrona (APC) al thread o l'intervallo di timeout trascorso. La matrice di oggetti può includere oggetti evento di input, specificati usando il parametro dwWakeMask.
Sintassi
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
Parametri
[in] nCount
Numero di handle di oggetto nella matrice a cui punta pHandles. Il numero massimo di handle di oggetti è MAXIMUM_WAIT_OBJECTS meno uno. Se questo parametro ha il valore zero, la funzione attende solo per un evento di input.
[in] pHandles
Matrice di handle di oggetti. Per un elenco dei tipi di oggetto i cui handle è possibile specificare, vedere la sezione Osservazioni più avanti in questo argomento. La matrice può contenere handle per più tipi di oggetti. Potrebbe non contenere più copie dello stesso handle.
Se uno di questi handle viene chiuso mentre l'attesa è ancora in sospeso, il comportamento della funzione non è definito.
Gli handle devono avere il diritto di accesso SYNCHRONIZE
[in] dwMilliseconds
Intervallo di timeout, espresso in millisecondi. Se viene specificato un valore diverso da zero, la funzione attende fino a quando gli oggetti specificati non vengono segnalate, viene accodata una routine di completamento di 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 gli oggetti specificati vengono segnalate o viene accodata una routine di completamento I/O o APC.
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] dwWakeMask
Tipi di input per i quali un handle di oggetto evento di input verrà aggiunto alla matrice di handle di oggetti. Questo parametro può essere qualsiasi combinazione dei valori elencati in GetQueueStatusflag parametro.
[in] dwFlags
Tipo di attesa. Questo parametro può essere uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
La funzione restituisce quando uno degli oggetti viene segnalato. Il valore restituito indica l'oggetto il cui stato ha causato la restituzione della funzione. |
|
La funzione restituisce anche se un APC è stato accodato al thread con QueueUserAPC mentre il thread è nello stato di attesa. |
|
La funzione restituisce se l'input esiste per la coda, anche se l'input è stato visualizzato (ma non rimosso) usando una chiamata a un'altra funzione, ad esempio PeekMessage. |
|
La funzione restituisce quando tutti gli oggetti nella matrice |
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. Si noti che WAIT_OBJECT_0 è definito come 0 e WAIT_ABANDONED_0 è definito come 0x00000080L.
| Codice/valore restituito | Descrizione |
|---|---|
|
Se viene utilizzato il flag MWMO_WAITALL, un valore restituito compreso nell'intervallo specificato indica che lo stato di tutti gli oggetti specificati viene segnalato. In caso contrario, il valore restituito meno WAIT_OBJECT_0 indica l'pHandles indice di matrice dell'oggetto che ha causato la restituzione della funzione. |
|
Il nuovo input del tipo specificato nella parametro dwWakeMask è disponibile nella coda di input del thread. Funzioni come PeekMessage, GetMessage, GetQueueStatuse WaitMessage contrassegnare i messaggi nella coda come messaggi precedenti. Pertanto, dopo aver chiamato una di queste funzioni, una chiamata successiva a MsgWaitForMultipleObjectsEx non restituirà fino all'arrivo di un nuovo input del tipo specificato.
Questo valore viene restituito anche quando si verifica un evento di sistema che richiede l'azione del thread, ad esempio l'attivazione in primo piano. Pertanto, msgWaitForMultipleObjectsEx può restituire anche se non è disponibile alcun input appropriato e anche se dwWakeMask è impostato su 0. In questo caso, chiamare GetMessage o PeekMessage per elaborare l'evento di sistema prima di provare a MsgWaitForMultipleObjectsEx di nuovo. |
|
Se viene utilizzato il flag MWMO_WAITALL, un valore restituito all'interno dell'intervallo specificato indica che lo stato di tutti gli oggetti specificati viene segnalato e almeno uno degli oggetti è un oggetto mutex abbandonato. In caso contrario, il valore restituito meno WAIT_ABANDONED_0 indica l'pHandles indice di matrice di un oggetto mutex abbandonato che ha causato la restituzione della funzione. 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. |
|
L'attesa è stata terminata da una o più chiamate di routine asincrone in coda al thread. |
|
Intervallo di timeout trascorso, ma non sono state soddisfatte le condizioni specificate dal dwFlags |
|
La funzione non è riuscita. Per ottenere informazioni estese sull'errore, chiamare GetLastError. |
Osservazioni
La funzione MsgWaitForMultipleObjectsEx
Quando dwFlags è zero, questa funzione controlla gli handle nella matrice in ordine a partire dall'indice 0, fino a quando uno degli oggetti non viene segnalato. Se vengono segnalate più oggetti, la funzione restituisce l'indice del primo handle nella matrice il cui oggetto è stato segnalato.
msgWaitForMultipleObjectsEx non restituisce se è presente un input non letto del tipo specificato nella coda di messaggi dopo che il thread ha chiamato una funzione per controllare la coda, a meno che non si usi il flag MWMO_INPUTAVAILABLE. Ciò è dovuto al fatto che funzioni come PeekMessage, GetMessage, GetQueueStatuse WaitMessage controllare la coda e quindi modificare le informazioni sullo stato per la coda in modo che l'input non venga più considerato nuovo. Una chiamata successiva a MsgWaitForMultipleObjectsEx non restituirà fino all'arrivo di un nuovo input del tipo specificato, a meno che non si usi il flag MWMO_INPUTAVAILABLE. Se questo flag non viene usato, l'input non letto esistente (ricevuto prima dell'ultima volta che il thread ha controllato la coda) viene ignorato.
La funzione modifica lo stato di alcuni tipi di oggetti di sincronizzazione. La modifica viene eseguita solo per l'oggetto o gli oggetti il cui stato segnalato ha causato la restituzione della funzione. Ad esempio, il sistema riduce di uno il numero di un oggetto semaforo. Per altre informazioni, vedere la documentazione relativa ai singoli oggetti di sincronizzazione.
La funzione
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaforo
- Filo
- Timer waitable
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Windows XP [solo app desktop] |
| server minimo supportato | Windows Server 2003 [solo app desktop] |
| piattaforma di destinazione | Finestre |
| intestazione |
winuser.h (include Windows.h) |
| libreria |
User32.lib |
| dll | User32.dll |