Funzione MsgWaitForMultipleObjects (winuser.h)
Attende che uno o tutti gli oggetti specificati si trovino nello stato segnalato o che scade l'intervallo di timeout. Gli oggetti possono includere oggetti evento di input, specificati usando il parametro dwWakeMask.
Per immettere uno stato di attesa avvisabile, usare la funzione MsgWaitForMultipleObjectsEx.
Sintassi
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
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 possono essere specificati, vedere la sezione Osservazioni seguente. La matrice può contenere handle di oggetti di tipi diversi. 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] fWaitAll
Se questo parametro è TRUE, la funzione restituisce quando gli stati di tutti gli oggetti nella pHandles matrice sono stati impostati su segnalato e viene ricevuto un evento di input. Se questo parametro è FALSE, la funzione restituisce quando lo stato di uno degli oggetti è impostato su segnalato o viene ricevuto un evento di input. In questo caso, il valore restituito indica l'oggetto il cui stato ha causato la restituzione della funzione.
[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 o trascorso l'intervallo. Se dwMilliseconds è zero, la funzione non immette uno stato di attesa se gli oggetti specificati non vengono segnalato; restituisce sempre immediatamente. Se dwMilliseconds è INFINITE, la funzione restituirà solo quando vengono segnalato gli oggetti specificati.
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.
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 bWaitAll è TRUE, un valore restituito all'interno dell'intervallo specificato indica che lo stato di tutti gli oggetti specificati viene segnalato. Se bWaitAll è FALSE, il valore restituito meno WAIT_OBJECT_0 indica l'pHandles indice di matrice dell'oggetto che ha soddisfatto l'attesa. |
|
Il nuovo input del tipo specificato nella parametro dwWakeMask è disponibile nella coda di input del thread. Funzioni come PeekMessage, GetMessagee WaitMessage contrassegnare i messaggi nella coda come messaggi precedenti. Pertanto, dopo aver chiamato una di queste funzioni, una chiamata successiva a MsgWaitForMultipleObjects 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, MsgWaitForMultipleObjects 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 MsgWaitForMultipleObjects di nuovo. |
|
Se bWaitAll è TRUE, 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. Se bWaitAll è FALSE, il valore restituito meno WAIT_ABANDONED_0 indica l'indice di matrice pHandles di un oggetto mutex abbandonato che ha soddisfatto l'attesa. 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'intervallo di timeout trascorso e le condizioni specificate dal bWaitAll e parametri di dwWakeMask non sono stati soddisfatti. |
|
La funzione non è riuscita. Per ottenere informazioni estese sull'errore, chiamare GetLastError. |
Osservazioni
La funzione MsgWaitForMultipleObjects 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.
Quando bWaitAll è TRUE, la funzione non modifica gli stati degli oggetti specificati finché gli stati di tutti gli oggetti non sono stati impostati su segnalato. Ad esempio, è possibile segnalare un mutex, ma il thread non ottiene la proprietà finché gli stati degli altri oggetti non sono stati impostati su segnalato. Nel frattempo, un altro thread può ottenere la proprietà del mutex, impostandone lo stato su non firmato.
Quando bWaitAll è TRUE, l'attesa della funzione viene completata solo quando gli stati di tutti gli oggetti sono stati impostati su segnalato e viene ricevuto un evento di input. Pertanto, l'impostazione di bWaitAll su TRUE impedisce l'elaborazione dell'input fino a quando lo stato di tutti gli oggetti nella matrice pHandles è stato impostato su segnalato. Per questo motivo, se si imposta bWaitAll su TRUE, è consigliabile usare un valore di timeout breve in dwMilliseconds. Se si dispone di un thread che crea finestre in attesa di tutti gli oggetti nella matrice pHandles, inclusi gli eventi di input specificati da dwWakeMask, senza intervallo di timeout, il sistema verrà deadlock. Ciò è dovuto al fatto che i thread che creano finestre devono elaborare i messaggi. DDE invia un messaggio a tutte le finestre del sistema. Pertanto, se un thread crea finestre, non impostare il parametro bWaitAll su TRUE nelle chiamate a MsgWaitForMultipleObjects creato da tale thread.
Quando bWaitAll è FALSE, questa funzione controlla gli handle nella matrice in ordine a partire dall'indice 0, fino a quando non viene segnalato uno degli oggetti. Se vengono segnalate più oggetti, la funzione restituisce l'indice del primo handle nella matrice il cui oggetto è stato segnalato.
MsgWaitForMultipleObjects 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. 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 MsgWaitForMultipleObjects non restituirà finché non arriva un nuovo input del tipo specificato. 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 conteggio di un oggetto semaforo viene ridotto di uno. Per altre informazioni, vedere la documentazione relativa ai singoli oggetti di sincronizzazione.
La funzione MsgWaitForMultipleObjects può specificare handle di uno dei tipi di oggetto seguenti nella matrice pHandles:
- 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 |