MsgWaitForMultipleObjects-Funktion (winuser.h)
Wartet, bis sich eines oder alle angegebenen Objekte im Signalzustand befinden oder das Timeoutintervall verstrichen ist. Die Objekte können Eingabeereignisobjekte enthalten, die Sie mit dem dwWakeMask-Parameter angeben.
Verwenden Sie die Funktion MsgWaitForMultipleObjectsEx , um einen warnbaren Wartezustand zu erhalten.
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 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 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 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] fWaitAll
Wenn dieser Parameter TRUE ist, gibt die Funktion zurück, wenn die Zustände aller Objekte im pHandles-Array auf signalisiert festgelegt wurden und ein Eingabeereignis empfangen wurde. Wenn dieser Parameter FALSE ist, gibt die Funktion zurück, wenn der Zustand eines der Objekte auf signalisiert oder ein Eingabeereignis empfangen wurde. In diesem Fall gibt der Rückgabewert das Objekt an, dessen Zustand die Funktion zurückgegeben hat.
[in] dwMilliseconds
Das Timeoutintervall in Millisekunden. Wenn ein Wert ohne Zero angegeben wird, wartet die Funktion, bis die angegebenen Objekte signalisiert werden oder das Intervall verstreicht. Wenn dwMilliseconds null ist, wird die Funktion nicht in den Wartezustand versetzt, wenn die angegebenen Objekte nicht signalisiert werden. Es wird immer sofort zurückgegeben. Wenn dwMillisecondsUNENDLICH ist, 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 enthält die Zeit, die in Zuständen mit geringer Leistung 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 dwMilliseconds-Wert enthält keine Zeit, die mit niedriger Leistung verbracht wurde. Staaten. Beispielsweise wird das Timeout nicht mehr 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.
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 bWaitAllTRUE ist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird. Wenn bWaitAllFALSE ist, gibt der Rückgabewert abzüglich WAIT_OBJECT_0 den pHandles-Arrayindex des Objekts an, das die Wartezeit erfüllt hat. |
|
Eine neue Eingabe des typs, der im dwWakeMask-Parameter angegeben ist, ist in der Eingabewarteschlange des Threads verfügbar. Funktionen wie PeekMessage, GetMessage und WaitMessage markieren Nachrichten in der Warteschlange als alte Nachrichten. Daher wird nach dem Aufrufen einer dieser Funktionen ein nachfolgender Aufruf von MsgWaitForMultipleObjects erst zurückgegeben, wenn eine neue Eingabe des angegebenen Typs eingeht.
Dieser Wert wird auch zurückgegeben, wenn ein Systemereignis auftritt, das die Aktion des Threads erfordert, z. B. die Vordergrundaktivierung. Daher kann MsgWaitForMultipleObjects 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 MsgWaitForMultipleObjects erneut versuchen. |
|
Wenn bWaitAllTRUE ist, gibt ein Rückgabewert innerhalb des angegebenen Bereichs an, dass der Zustand aller angegebenen Objekte signalisiert wird und mindestens eines der Objekte ein verlassenes Mutex-Objekt ist. Wenn bWaitAllFALSE 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 nicht signalisiert festgelegt.
Wenn der Mutex Informationen zu persistenten Zustanden schützt, sollten Sie ihn auf Konsistenz überprüfen. |
|
Das Timeoutintervall ist verstrichen, und die von den Parametern bWaitAll und dwWakeMask angegebenen Bedingungen wurden nicht erfüllt. |
|
Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. |
Hinweise
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 bWaitAllTRUE ist, ändert die Funktion die Zustände der angegebenen Objekte erst, wenn der Status aller Objekte auf signalisiert festgelegt wurde. Beispielsweise kann ein Mutex signalisiert werden, aber der Thread erhält erst dann 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 signalisiert festgelegt wird.
Wenn bWaitAllTRUE ist, wird die Wartezeit der Funktion nur abgeschlossen, wenn der Status aller Objekte auf signalisiert festgelegt wurde und ein Eingabeereignis empfangen wurde. Wenn Sie bWaitAll auf TRUE festlegen, wird daher verhindert, dass Eingaben verarbeitet werden, bis der Zustand aller Objekte im pHandles-Array auf signalisiert wurde. Wenn Sie bWaitAll auf TRUE festlegen, sollten Sie daher einen kurzen Timeoutwert in dwMillisekunden verwenden. Wenn Sie über einen Thread verfügen, der Fenster erstellt, die auf alle Objekte im pHandles-Array warten, einschließlich eingaberelevanter Ereignisse, die von dwWakeMask angegeben werden, ohne Timeoutintervall, wird das System deadlockt. Dies liegt daran, dass Threads, die Fenster erstellen, Nachrichten verarbeiten müssen. DDE sendet eine Nachricht an alle Fenster im System. Wenn ein Thread Daher Fenster erstellt, legen Sie den bWaitAll-Parameter in Aufrufen von MsgWaitForMultipleObjects aus diesem Thread nicht auf TRUE fest.
Wenn bWaitAllFALSE 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.
MsgWaitForMultipleObjects 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. 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 MsgWaitForMultipleObjects wird erst zurückgegeben, wenn eine neue Eingabe des angegebenen Typs eingeht. Die vorhandene ungelesene Eingabe (empfangen vor dem letzten Überprüfen der Warteschlange durch den Thread) wird 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 Funktion zurückgegeben hat. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert. Weitere Informationen finden Sie in der Dokumentation zu den einzelnen Synchronisierungsobjekten.
Die MsgWaitForMultipleObjects-Funktion kann Handles der folgenden Objekttypen im pHandles-Array angeben:
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Benachrichtigung zu Speicherressourcen
- Mutex
- Prozess
- Semaphore
- Thread
- Wartebarer Timer
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | winuser.h (windows.h einschließen) |
| Bibliothek | User32.lib |
| DLL | User32.dll |