Funzione MsgWaitForMultipleObjectsEx (winuser.h)
Attende fino a quando uno o tutti gli oggetti specificati si trovano 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. 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 oggetti 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 a 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 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 gli oggetti specificati non vengono segnalati, 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 gli oggetti specificati vengono segnalati 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] dwWakeMask
I tipi di input per i quali verrà aggiunto un handle dell'oggetto evento di input alla matrice di handle degli oggetti. Questo parametro può essere una combinazione dei valori elencati nel parametro FlagGetQueueStatus.
[in] dwFlags
Tipo di attesa. Questo parametro può essere uno o più dei valori seguenti.
| Valore | Significato |
|---|---|
|
La funzione restituisce quando viene segnalato uno degli oggetti. 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 si trova nello stato di attesa. |
|
La funzione restituisce se esiste l'input 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 pHandles vengono segnalati e viene ricevuto un evento di input, tutti contemporaneamente. |
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 usato il flag MWMO_WAITALL , un valore restituito all'interno dell'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'indice della matrice pHandles dell'oggetto che ha causato la restituzione della funzione. |
|
Il nuovo input del tipo specificato nel parametro dwWakeMask è disponibile nella coda di input del thread. Funzioni come PeekMessage, GetMessage, GetQueueStatus e WaitMessage contrassegnano i messaggi nella coda come messaggi precedenti. Pertanto, dopo aver chiamato una di queste funzioni, una chiamata successiva a MsgWaitForMultipleObjectsEx non restituirà finché non arriva un nuovo input del tipo specificato.
Questo valore viene restituito anche dopo l'occorrenza di 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 di nuovo la chiamata a MsgWaitForMultipleObjectsEx . |
|
Se viene usato 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'indice della matrice pHandles 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 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. |
|
L'intervallo di timeout trascorso, ma le condizioni specificate dai parametri dwFlags e dwWakeMask non sono state soddisfatte. |
|
La funzione non è riuscita. Per informazioni dettagliate sull'errore, chiamare GetLastError. |
Commenti
La funzione MsgWaitForMultipleObjectsEx determina se sono state soddisfatte le condizioni specificate da dwWakeMask e dwFlags . Se le condizioni non sono state soddisfatte, 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.
Quando dwFlags è zero, questa funzione controlla gli handle nella matrice in ordine a partire dall'indice 0, fino a quando non viene segnalato uno degli oggetti. Se più oggetti diventano segnalati, 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 del messaggio dopo che il thread ha chiamato una funzione per controllare la coda, a meno che non si usi il flag di MWMO_INPUTAVAILABLE . Questo perché le funzioni come PeekMessage, GetMessage, GetQueueStatus e WaitMessage controllano la coda e quindi modificano le informazioni sullo stato per la coda in modo che l'input non venga più considerato nuovo. Una chiamata successiva a MsgWaitForMultipleObjectsEx non restituirà finché non arriva un nuovo input del tipo specificato, a meno che non si usi il flag di 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 si verifica solo per l'oggetto o gli oggetti lo stato segnalato ha causato la restituzione della funzione. Ad esempio, il sistema riduce il conteggio di un oggetto semaforo per uno. Per altre informazioni, vedere la documentazione per i singoli oggetti di sincronizzazione.
La funzione MsgWaitForMultipleObjectsEx può specificare handle di uno dei tipi di oggetti seguenti nella matrice pHandles :
- Notifica di modifica
- Input della console
- Evento
- Notifica delle risorse di memoria
- Mutex
- Processo
- Semaphore
- Thread
- Timer attendebile
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows Server 2003 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | winuser.h (include Windows.h) |
| Libreria | User32.lib |
| DLL | User32.dll |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per