MsgWaitForMultipleObjects-Funktion (winuser.h)
Wartet, bis mindestens eins der angegebenen Objekte im Signalzustand oder im Timeoutintervall verstrichen ist. Die Objekte können Eingabeereignisobjekte enthalten, die Sie mithilfe des dwWakeMask--Parameters angeben.
Verwenden Sie zum Eingeben eines warnbaren Wartezustands die MsgWaitForMultipleObjectsEx--Funktion.
Syntax
DWORD MsgWaitForMultipleObjects(
[in] DWORD nCount,
[in] const HANDLE *pHandles,
[in] BOOL fWaitAll,
[in] DWORD dwMilliseconds,
[in] DWORD dwWakeMask
);
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 angegeben werden können, finden Sie im folgenden Abschnitt "Hinweise". Das Array kann Handles von Objekten unterschiedlicher Typen 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] fWaitAll
Wenn dieser Parameter TRUEist, gibt die Funktion zurück, wenn die Zustände aller Objekte im pHandles Array auf signalisiert und ein Eingabeereignis empfangen wurde. Wenn dieser Parameter FALSEist, gibt die Funktion zurück, wenn der Status eines der Objekte auf signalisiert oder ein Eingabeereignis empfangen wurde. In diesem Fall gibt der Rückgabewert das Objekt an, dessen Zustand dazu führte, dass die Funktion zurückgegeben wurde.
[in] dwMilliseconds
Das Timeoutintervall in Millisekunden. Wenn ein Wert ungleich Null angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert oder das Intervall verstrichen ist. Wenn dwMilliseconds null ist, gibt die Funktion keinen Wartezustand ein, wenn die angegebenen Objekte nicht signalisiert werden; es wird immer sofort zurückgegeben. Wenn dwMillisecondsINFINITEist, wird die Funktion nur zurückgegeben, wenn die angegebenen Objekte signalisiert werden.
Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 und Windows Server 2008 R2: Der dwMilliseconds- Wert umfasst Zeit, die in Energiesparzuständen aufgewendet wurde. Beispielsweise wird das Timeout weiter gezählt, während der Computer eingeschlafen ist.
Windows 8 und neuer, Windows Server 2012 und höher: Der wert dwMilliseconds 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.
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 |
|---|---|
|
Wenn bWaitAllTRUEist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird. Wenn bWaitAll-FALSE-ist, gibt der Rückgabewert minus WAIT_OBJECT_0 den pHandles Arrayindex des Objekts an, das die Wartezeit erfüllt hat. |
|
Neue Eingabe des typs, der in der dwWakeMask Parameter angegeben ist, ist in der Eingabewarteschlange des Threads verfügbar. Funktionen wie PeekMessage-, GetMessage-und WaitMessage Nachrichten in der Warteschlange als alte Nachrichten markieren. Nachdem Sie eine dieser Funktionen aufgerufen haben, wird daher erst ein nachfolgenden Aufruf von MsgWaitForMultipleObjects 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 MsgWaitForMultipleObjects 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 MsgWaitForMultipleObjects erneut versuchen. |
|
Wenn bWaitAll-TRUEist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert ist und mindestens eines der Objekte ein verlassenes Mutex-Objekt ist. Wenn bWaitAll-FALSE-ist, gibt der Rückgabewert minus WAIT_ABANDONED_0 den pHandles Arrayindex eines verlassenen Mutex-Objekts an, das die Wartezeit erfüllt hat. 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. |
|
Das verstrichene Timeoutintervall und die bedingungen, die durch die bWaitAll und dwWakeMask Parameter angegeben wurden, wurden nicht erfüllt. |
|
Fehler bei der Funktion. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. |
Bemerkungen
Die MsgWaitForMultipleObjects--Funktion bestimmt, ob die Wartekriterien erfüllt wurden. Wenn die Kriterien 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 bWaitAll-TRUEist, ändert die Funktion nicht die Zustände der angegebenen Objekte, bis die Zustände aller Objekte signalisiert wurden. Beispielsweise kann ein Mutex signalisiert werden, aber der Thread erhält erst den Besitz, wenn die Zustände der anderen Objekte ebenfalls auf signalisiert wurden. In der Zwischenzeit kann ein anderer Thread den Besitz des Mutex erhalten, wodurch sein Zustand auf nicht signaliert festgelegt wird.
Wenn bWaitAll-TRUEist, wird die Wartezeit der Funktion nur abgeschlossen, wenn die Zustände aller Objekte auf signalisiert festgelegt wurden und ein Eingabeereignis empfangen wurde. Das Festlegen bWaitAll daher auf TRUE verhindert, dass eingaben verarbeitet werden, bis der Status aller Objekte im pHandles Array signalisiert wurde. Wenn Sie aus diesem Grund bWaitAll auf TRUEfestlegen, sollten Sie in dwMillisecondseinen kurzen Timeoutwert verwenden. Wenn Sie über einen Thread verfügen, der Fenster erstellt, die auf alle Objekte im pHandles Array warten, einschließlich eingabeereignisse, die durch dwWakeMaskangegeben werden, ohne Timeoutintervall, wird das System inaktiviert. Dies liegt daran, dass Threads, die Fenster erstellen, Nachrichten verarbeiten müssen. DDE sendet Eine Nachricht an alle Fenster im System. Legen Sie daher, wenn ein Thread Fenster erstellt, den bWaitAll Parameter nicht auf true in Aufrufen von MsgWaitForMultipleObjects aus diesem Thread.
Wenn bWaitAllFALSEist, ü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.
MsgWaitForMultipleObjects 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. 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 MsgWaitForMultipleObjects wird erst zurückgegeben, wenn neue Eingaben des angegebenen Typs eingehen. Die vorhandene ungelesene Eingabe (die vor dem letzten Überprüfen des Threads in der Warteschlange empfangen wurde) wird 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 wird die Anzahl eines Semaphorobjekts um ein Objekt verringert. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.
Die MsgWaitForMultipleObjects--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 |