WaitForMultipleObjectsEx-Funktion (synchapi.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.
Syntax
DWORD WaitForMultipleObjectsEx(
[in] DWORD nCount,
[in] const HANDLE *lpHandles,
[in] BOOL bWaitAll,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parameter
[in] nCount
Die Anzahl der Objekthandles, auf die im Array gewartet werden soll, auf das durch lpHandlesverwiesen wird. Die maximale Anzahl von Objektziehpunkten ist MAXIMUM_WAIT_OBJECTS. Dieser Parameter darf nicht null sein.
[in] lpHandles
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] bWaitAll
Wenn dieser Parameter TRUEist, gibt die Funktion zurück, wenn der Zustand aller Objekte im lpHandles Array auf signalisiert festgelegt ist. Wenn FALSE, gibt die Funktion zurück, wenn der Zustand eines der Objekte auf signalisiert festgelegt ist. Im letzteren Fall gibt der Rückgabewert das Objekt an, dessen Status die Funktion zurückgegeben hat.
[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 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] bAlertable
Wenn dieser Parameter TRUE ist und sich der Thread im Wartezustand befindet, gibt die Funktion zurück, wenn das System eine E/A-Abschlussroutine oder APC in die Warteschlange stellt und der Thread die Routine oder Funktion ausführt. Andernfalls wird die Funktion nicht zurückgegeben, und die Abschlussroutine oder die APC-Funktion wird nicht ausgeführt.
Eine Abschlussroutine wird in die Warteschlange gestellt, wenn die ReadFileEx- oder WriteFileEx- funktion, in der sie angegeben wurde, abgeschlossen wurde. Die Wartefunktion wird zurückgegeben und die Abschlussroutine wird nur aufgerufen, wenn bAlertableTRUE ist und der aufrufende Thread der Thread ist, der den Lese- oder Schreibvorgang initiiert hat. Ein APC wird in die Warteschlange gestellt, wenn Sie QueueUserAPC-aufrufen.
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 in diesem Bereich an, dass der Status aller angegebenen Objekte signalisiert wird.
Wenn bWaitAllFALSEist, gibt der Rückgabewert minus WAIT_OBJECT_0 den lpHandles Arrayindex des Objekts an, das die Wartezeit erfüllt hat. Wenn während des Aufrufs mehrere Objekte signalisiert wurden, ist dies der Arrayindex des signalisierten Objekts mit dem kleinsten Indexwert aller signalisierten Objekte. |
|
Wenn bWaitAll-TRUEist, gibt ein Rückgabewert in diesem Bereich an, dass der Zustand aller angegebenen Objekte signalisiert ist und mindestens eines der Objekte ein verlassenes Mutex-Objekt ist.
Wenn bWaitAll-FALSEist, gibt der Rückgabewert minus WAIT_ABANDONED_0 den lpHandles 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 ein Mutex beständige Zustandsinformationen schützt, sollten Sie ihn auf Konsistenz überprüfen. |
|
Die Wartezeit wurde durch einen oder mehrere Benutzermodus beendet, asynchrone Prozeduraufrufe (APC) in die Warteschlange des Threads eingereiht wurden. |
|
Das verstrichene Timeoutintervall, die durch den bWaitAll Parameter angegebenen Bedingungen wurden nicht erfüllt, und es werden keine Abschlussroutinen in die Warteschlange gestellt. |
|
Fehler bei der Funktion. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. |
Bemerkungen
Die funktion WaitForMultipleObjectsEx 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, wird der Wartevorgang der Funktion nur abgeschlossen, wenn die Zustände aller Objekte auf signalisiert wurden. Die Funktion ändert die Zustände der angegebenen Objekte erst, wenn 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 signalisiert werden. In der Zwischenzeit kann ein anderer Thread den Besitz des Mutex erhalten, wodurch sein Zustand auf nicht signaliert festgelegt wird.
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.
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.
Verwenden Sie eine der folgenden Methoden, um auf mehr als MAXIMUM_WAIT_OBJECTS Handles zu warten:
- Erstellen Sie einen Thread, um auf MAXIMUM_WAIT_OBJECTS Handles zu warten, und warten Sie dann auf diesen Thread und die anderen Handles. Verwenden Sie diese Technik, um die Ziehpunkte in Gruppen von MAXIMUM_WAIT_OBJECTSaufzuteilen.
- Rufen Sie RegisterWaitForSingleObject oder SetThreadpoolWait- auf, um auf jedes Handle zu warten. Der Threadpool wartet effizient auf den Handles und weist einen Arbeitsthread zu, nachdem das Objekt signalisiert wurde oder das Timeoutintervall abläuft.
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Speicherressourcenbenachrichtigung
- Mutex
- Prozess
- Semaphor
- Faden
- Wartezeitgeber
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [Desktop-Apps | UWP-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform- | Fenster |
| Header- | synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Library | Kernel32.lib |
| DLL- | Kernel32.dll |