MsgWaitForMultipleObjectsEx-Funktion (winuser.h)
Wartet, bis sich eines oder alle angegebenen Objekte im signalierten Zustand befinden, bis eine E/A-Vervollständigungsroutine oder ein asynchroner Prozeduraufruf (APC) für den Thread in die Warteschlange eingereiht wird oder das Timeoutintervall verstrichen ist. Das Array von -Objekten kann Eingabeereignisobjekte enthalten, die Sie mit dem dwWakeMask-Parameter angeben.
Syntax
DWORD MsgWaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask,
[in] DWORD dwFlags
);
Parameter
[in] nCount
Die Anzahl der Objekthandles im Array, auf das von pHandles verwiesen wird. Die maximale Anzahl von Objekthandles ist MAXIMUM_WAIT_OBJECTS minus 1. Wenn dieser Parameter den Wert 0 aufweist, wartet die Funktion nur auf ein Eingabeereignis.
[in] pHandles
Ein Array von Objekthandles. Eine Liste der Objekttypen, deren Handles Sie angeben können, finden Sie im Abschnitt Hinweise weiter unten in diesem Thema. Das Array kann Handles für mehrere Objekttypen enthalten. Es darf nicht mehrere Kopien desselben Handle enthalten.
Wenn eines dieser Handles geschlossen wird, während die Wartezeit noch aussteht, ist das Verhalten der Funktion nicht definiert.
Die Handles müssen über das Synchronzugriffsrecht verfügen. Weitere Informationen finden Sie unter Standardzugriffsrechte.
[in] dwMilliseconds
Das Timeoutintervall in Millisekunden. Wenn ein nichtzero-Wert angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert werden, bis eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird oder das Intervall verstreicht. Wenn dwMilliseconds null ist, gibt die Funktion keinen Wartezustand auf, wenn die Kriterien nicht erfüllt sind. Es wird immer sofort zurückgegeben. Wenn dwMillisecondsINFINITE ist, wird die Funktion nur zurückgegeben, wenn die angegebenen Objekte signalisiert oder eine E/A-Vervollständigungsroutine oder APC in eine Warteschlange eingereiht werden.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der Wert dwMilliseconds enthält die Zeit, die in Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout während des Ruhezustands des Computers immer wieder heruntergezählt.
Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 und Windows Server 2016: Der Wert dwMilliseconds enthält keine Zeit, die mit Zuständen mit niedriger Energie verbracht wurde. Beispielsweise wird das Timeout nicht heruntergezählt, während sich der Computer im Ruhezustand befindet.
[in] dwWakeMask
Die Eingabetypen, für die dem Array von Objekthandles ein Eingabeereignisobjekthandle hinzugefügt wird. Bei diesem Parameter kann es sich um eine beliebige Kombination der werte handeln, die im Parameter GetQueueStatusflags aufgeführt sind.
[in] dwFlags
Der Wartetyp. Dieser Parameter kann einen oder mehrere der folgenden Werte aufweisen.
| Wert | Bedeutung |
|---|---|
|
Die Funktion gibt zurück, wenn eines der Objekte signalisiert wird. Der Rückgabewert gibt das Objekt an, dessen Zustand die Funktion zurückgegeben hat. |
|
Die Funktion gibt auch zurück, wenn ein APC mit QueueUserAPC für den Thread in eine Warteschlange eingereiht wurde, während sich der Thread im Wartezustand befindet. |
|
Die Funktion gibt zurück, wenn eine Eingabe für die Warteschlange vorhanden ist, auch wenn die Eingabe mithilfe eines Aufrufs einer anderen Funktion wie PeekMessage erkannt (aber nicht entfernt wurde). |
|
Die Funktion gibt zurück, wenn alle Objekte im pHandles-Array signalisiert werden und ein Eingabeereignis gleichzeitig empfangen wurde. |
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt der Rückgabewert das Ereignis an, durch das die Funktion zurückgegeben wurde. Dieses Argument einen der folgenden Werte annehmen. (Beachten Sie, dass WAIT_OBJECT_0 als 0 und WAIT_ABANDONED_0 als 0x00000080L definiert ist.)
| Rückgabecode/-wert | BESCHREIBUNG |
|---|---|
|
Wenn das flag MWMO_WAITALL verwendet wird, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird. Andernfalls gibt der Rückgabewert abzüglich WAIT_OBJECT_0 den pHandles-Arrayindex des Objekts an, durch das die Funktion zurückgegeben wurde. |
|
Eine neue Eingabe des typs, der im dwWakeMask-Parameter angegeben ist, ist in der Eingabewarteschlange des Threads verfügbar. Funktionen wie PeekMessage, GetMessage, GetQueueStatus und WaitMessage markieren Nachrichten in der Warteschlange als alte Nachrichten. Daher wird nach dem Aufrufen einer dieser Funktionen ein nachfolgender Aufruf von MsgWaitForMultipleObjectsEx erst zurückgegeben, wenn eine neue Eingabe des angegebenen Typs eintrifft.
Dieser Wert wird auch zurückgegeben, wenn ein Systemereignis auftritt, das die Aktion des Threads erfordert, z. B. die Vordergrundaktivierung. Daher kann MsgWaitForMultipleObjectsEx zurückgegeben werden, obwohl keine entsprechende Eingabe verfügbar ist und auch wenn dwWakeMask auf 0 festgelegt ist. Rufen Sie in diesem Fall GetMessage oder PeekMessage auf, um das Systemereignis zu verarbeiten, bevor Sie den Aufruf von MsgWaitForMultipleObjectsEx erneut versuchen. |
|
Wenn das Flag MWMO_WAITALL verwendet wird, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird und dass mindestens eines der Objekte ein verlassenes Mutex-Objekt ist. Andernfalls gibt der Rückgabewert ab WAIT_ABANDONED_0 den pHandles-Arrayindex eines verlassenen Mutex-Objekts an, durch das die Funktion zurückgegeben wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex wird auf nicht signalisiert festgelegt.
Wenn der Mutex Informationen zu persistenten Zustanden schützt, sollten Sie ihn auf Konsistenz überprüfen. |
|
Die Wartezeit wurde durch einen oder mehrere asynchrone Prozeduraufrufe im Benutzermodus beendet, die in die Warteschlange des Threads eingereiht wurden. |
|
Das Timeoutintervall ist verstrichen, aber die von den Parametern dwFlags und dwWakeMask angegebenen Bedingungen wurden nicht erfüllt. |
|
Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. |
Hinweise
Die MsgWaitForMultipleObjectsEx-Funktion bestimmt, ob die von dwWakeMask und dwFlags angegebenen Bedingungen erfüllt wurden. Wenn die Bedingungen nicht erfüllt wurden, wechselt der aufrufende Thread in den Wartezustand, bis die Bedingungen der Wartekriterien erfüllt wurden oder das Timeoutintervall verstreicht.
Wenn dwFlags 0 ist, überprüft diese Funktion die Handles im Array in der Reihenfolge ab Index 0, bis eines der Objekte signalisiert wird. Wenn mehrere Objekte signalisiert werden, gibt die Funktion den Index des ersten Handles in dem Array zurück, dessen Objekt signalisiert wurde.
MsgWaitForMultipleObjectsEx wird nicht zurückgegeben, wenn ungelesene Eingaben des angegebenen Typs in der Nachrichtenwarteschlange vorhanden sind, nachdem der Thread eine Funktion zum Überprüfen der Warteschlange aufgerufen hat, es sei denn, Sie verwenden das MWMO_INPUTAVAILABLE-Flag . Dies liegt daran, dass Funktionen wie PeekMessage, GetMessage, GetQueueStatus und WaitMessage die Warteschlange überprüfen und dann die Statusinformationen für die Warteschlange ändern, sodass die Eingabe nicht mehr als neu betrachtet wird. Ein nachfolgender Aufruf von MsgWaitForMultipleObjectsEx wird erst zurückgegeben, wenn eine neue Eingabe des angegebenen Typs eintrifft, es sei denn, Sie verwenden das flag MWMO_INPUTAVAILABLE . Wenn dieses Flag nicht verwendet wird, wird die vorhandene ungelesene Eingabe (die vor dem letzten Überprüfen der Warteschlange vom Thread empfangen wurde) ignoriert.
Die Funktion ändert den Zustand einiger Typen von Synchronisierungsobjekten. Die Änderung erfolgt nur für das Objekt oder die Objekte, deren signalisierter Zustand die Rückgabe der Funktion bewirkt hat. Beispielsweise verringert das System die Anzahl eines Semaphorobjekts um eins. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.
Die MsgWaitForMultipleObjectsEx-Funktion kann Handles der folgenden Objekttypen im pHandles-Array angeben:
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Benachrichtigung zu Speicherressourcen
- Mutex
- Prozess
- Semaphore
- Thread
- Wartebarer Timer
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winuser.h (einschließlich Windows.h) |
| Bibliothek | User32.lib |
| DLL | User32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für