MsgWaitForMultipleObjectsEx-Funktion (winuser.h)

Wartet, bis sich ein oder alle angegebenen Objekte im Signalzustand befinden, eine E/A-Vervollständigungsroutine oder ein asynchroner Prozeduraufruf (APC) im Thread in die Warteschlange gestellt wird oder das Timeoutintervall verstrichen ist. Das Array von Objekten kann Eingabeereignisobjekte enthalten, die Sie mithilfe des dwWakeMask--Parameters 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 Objektziehpunkte im Array, auf die durch pHandlesverwiesen wird. Die maximale Anzahl von Objekthandles ist MAXIMUM_WAIT_OBJECTS minus 1. Wenn dieser Parameter den Wert Null hat, 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 Handles enthalten.

Wenn eines dieser Handles geschlossen ist, während die Wartezeit noch aussteht, ist das Verhalten der Funktion nicht definiert.

Die Handles müssen über das SYNCHRONIZE Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Standardzugriffsrechte.

[in] dwMilliseconds

Das Timeoutintervall in Millisekunden. Wenn ein Wert ungleich Null angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert werden, eine E/A-Vervollständigungsroutine oder ein APC in die Warteschlange gestellt wird oder das Intervall verstrichen ist. Wenn dwMilliseconds null ist, gibt die Funktion keinen Wartezustand ein, wenn die Kriterien nicht erfüllt sind; es wird immer sofort zurückgegeben. Wenn dwMillisecondsINFINITEist, wird die Funktion nur zurückgegeben, wenn die angegebenen Objekte signalisiert werden oder eine E/A-Abschlussroutine oder APC in die Warteschlange gestellt wird.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der wert dwMilliseconds enthält zeitverwendete Zeit in Energiesparzuständen. Beispielsweise wird das Timeout weiter gezählt, während der Computer eingeschlafen ist.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 und Windows Server 2016: Der dwMilliseconds Wert enthält keine Zeit, die in Energiesparzuständen aufgewendet wurde. Beispielsweise wird das Timeout nicht weiter gezählt, während der Computer eingeschlafen ist.

[in] dwWakeMask

Die Eingabetypen, für die ein Eingabeereignisobjekthandle dem Array von Objekthandles hinzugefügt wird. Dieser Parameter kann eine beliebige Kombination der werte sein, die in GetQueueStatusFlags Parameter aufgeführt sind.

[in] dwFlags

Der Wartetyp. Dieser Parameter kann einen oder mehrere der folgenden Werte sein.

Wert	Bedeutung
0	Die Funktion gibt zurück, wenn eines der Objekte signalisiert wird. Der Rückgabewert gibt das Objekt an, dessen Zustand dazu führte, dass die Funktion zurückgegeben wurde.
MWMO_ALERTABLE 0x0002	Die Funktion gibt auch zurück, wenn ein APC mit QueueUserAPC- in die Warteschlange gestellt wurde, während sich der Thread im Wartezustand befindet.
MWMO_INPUTAVAILABLE 0x0004	Die Funktion gibt zurück, wenn eingaben für die Warteschlange vorhanden sind, auch wenn die Eingabe mithilfe eines Aufrufs für eine andere Funktion angezeigt (aber nicht entfernt) wurde, z. B. PeekMessage-.
MWMO_WAITALL 0x0001	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, das dazu führte, dass die Funktion zurückgegeben wurde. Dabei kann es sich um einen der folgenden Werte handeln. (Beachten Sie, dass WAIT_OBJECT_0 als 0 definiert ist und WAIT_ABANDONED_0 als 0x00000080L definiert ist.)

Zurückgeben von Code/Wert	Beschreibung
WAIT_OBJECT_0 bis (WAIT_OBJECT_0 + nCount - 1)	Wenn das flag MWMO_WAITALL verwendet wird, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Status aller angegebenen Objekte signalisiert wird. Andernfalls gibt der Rückgabewert minus WAIT_OBJECT_0 den pHandles Arrayindex des Objekts an, das dazu führte, dass die Funktion zurückgegeben wurde.
WAIT_OBJECT_0 + nCount-	Neue Eingabe des typs, der in der dwWakeMask Parameter angegeben ist, ist in der Eingabewarteschlange des Threads verfügbar. Funktionen wie PeekMessage, GetMessage, GetQueueStatusund WaitMessage Nachrichten in der Warteschlange als alte Nachrichten markieren. Nachdem Sie eine dieser Funktionen aufgerufen haben, wird daher erst ein nachfolgenden Aufruf von MsgWaitForMultipleObjectsEx zurückgegeben, wenn neue Eingaben des angegebenen Typs eingehen. Dieser Wert wird auch beim Auftreten eines Systemereignisses zurückgegeben, das die Aktion des Threads erfordert, z. B. die Vordergrundaktivierung. Daher können MsgWaitForMultipleObjectsEx- zurückgeben, 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.
WAIT_ABANDONED_0 bis (WAIT_ABANDONED_0 + nCount - 1)	Wenn das flag MWMO_WAITALL verwendet wird, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Status aller angegebenen Objekte signalisiert wird und mindestens eines der Objekte ein verlassenes Mutex-Objekt ist. Andernfalls gibt der Rückgabewert minus WAIT_ABANDONED_0 den pHandles Arrayindex eines verlassenen Mutex-Objekts an, das dazu führte, dass die Funktion zurückgegeben wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex wird auf nichtsignaliert festgelegt. Wenn der Mutex beständige Zustandsinformationen schützt, sollten Sie dies auf Konsistenz überprüfen.
WAIT_IO_COMPLETION 0x0000000C0L	Die Wartezeit wurde durch einen oder mehrere Benutzermodus beendet, asynchrone Prozeduraufrufe (APC) in die Warteschlange des Threads eingereiht wurden.
WAIT_TIMEOUT 258L	Das Timeoutintervall ist abgelaufen, aber die durch die dwFlags angegebenen Bedingungen und dwWakeMask Parameter wurden nicht erfüllt.
WAIT_FAILED (DWORD)0xFFFFFFFF	Fehler bei der Funktion. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Die funktion MsgWaitForMultipleObjectsEx bestimmt, ob die durch 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 verstrichen ist.

Wenn dwFlags null ist, überprüft diese Funktion die Ziehpunkte im Array in der Reihenfolge beginnend mit Index 0, bis eines der Objekte signalisiert wird. Wenn mehrere Objekte signalisiert werden, gibt die Funktion den Index des ersten Handles im Array zurück, dessen Objekt signalisiert wurde.

MsgWaitForMultipleObjectsEx gibt nicht zurück, wenn ungelesene Eingaben des angegebenen Typs in der Nachrichtenwarteschlange vorhanden sind, nachdem der Thread eine Funktion aufgerufen hat, um die Warteschlange zu überprüfen, es sei denn, Sie verwenden das MWMO_INPUTAVAILABLE Flag. Dies liegt daran, dass Funktionen wie PeekMessage, GetMessage, GetQueueStatusund Wait Message die Warteschlange überprüfen und dann die Statusinformationen für die Warteschlange ändern, sodass die Eingabe nicht mehr als neu betrachtet wird. Ein anschließender Aufruf von MsgWaitForMultipleObjectsEx- wird erst zurückgegeben, wenn neue Eingaben des angegebenen Typs eingehen, es sei denn, Sie verwenden das MWMO_INPUTAVAILABLE-Flag. Wenn dieses Flag nicht verwendet wird, wird die vorhandene ungelesene Eingabe (die vor dem letzten Überprüfen des Threads in der Warteschlange empfangen wurde) ignoriert.

Die Funktion ändert den Status einiger Synchronisierungsobjekte. Änderungen treten nur für das Objekt oder die Objekte auf, deren signalisierter Zustand dazu führte, dass die Funktion zurückgegeben wurde. Beispielsweise verringert das System die Anzahl eines Semaphorobjekts um ein Objekt. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.

Die MsgWaitForMultipleObjectsEx--Funktion kann Handles aller folgenden Objekttypen im pHandles- Array angeben:

• Änderungsbenachrichtigung
• Konsoleneingabe
• Ereignis
• Speicherressourcenbenachrichtigung
• Mutex
• Prozess
• Semaphor
• Faden
• Wartezeitgeber

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll

Siehe auch

Synchronisierungsfunktionen

Wait Functions