WaitForSingleObject-Funktion (synchapi.h)
Wartet, bis sich das angegebene Objekt im Signalzustand befindet oder das Timeoutintervall verstrichen ist.
Verwenden Sie die WaitForSingleObjectEx-Funktion , um einen warnbaren Wartezustand einzugeben. Um auf mehrere Objekte zu warten, verwenden Sie WaitForMultipleObjects.
Syntax
DWORD WaitForSingleObject(
[in] HANDLE hHandle,
[in] DWORD dwMilliseconds
);
Parameter
[in] hHandle
Ein Handle für das -Objekt. Eine Liste der Objekttypen, deren Handles angegeben werden können, finden Sie im folgenden Abschnitt Hinweise.
Wenn dieses Handle geschlossen wird, während die Wartezeit noch aussteht, ist das Verhalten der Funktion undefiniert.
Das Handle muss ü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 das Objekt signalisiert wird oder das Intervall verstrichen ist. Wenn dwMilliseconds null ist, wechselt die Funktion nicht in den Wartezustand, wenn das Objekt nicht signalisiert wird. es wird immer sofort zurückgegeben. Wenn dwMillisecondsINFINITE ist, gibt die Funktion nur zurück, wenn das Objekt signalisiert wird.
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.
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.
| Rückgabecode/-wert | BESCHREIBUNG |
|---|---|
|
Das angegebene Objekt ist ein Mutex-Objekt, das nicht von dem Thread freigegeben wurde, der das Mutex-Objekt besitzt, bevor der besitzende Thread beendet wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex-Zustand wird auf nicht signalisiert festgelegt.
Wenn der Mutex permanente Zustandsinformationen schützt, sollten Sie ihn auf Konsistenz überprüfen. |
|
Der Zustand des angegebenen Objekts wird signalisiert. |
|
Das Timeoutintervall ist verstrichen, und der Zustand des Objekts ist nicht signalisiert. |
|
Die Funktion ist fehlgeschlagen. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf. |
Hinweise
Die WaitForSingleObject-Funktion überprüft den aktuellen Zustand des angegebenen Objekts. Wenn der Zustand des Objekts nicht signalisiert ist, wechselt der aufrufende Thread in den Wartezustand, bis das Objekt signalisiert wird oder das Timeoutintervall verstrichen ist.
Die -Funktion ändert den Zustand einiger Typen von Synchronisierungsobjekten. Die Änderung erfolgt nur für das Objekt, dessen signalisierter Zustand dazu geführt hat, dass die Funktion zurückgegeben wurde. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert.
Die WaitForSingleObject-Funktion kann auf die folgenden Objekte warten:
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Benachrichtigung zur Speicherressource
- Mutex
- Prozess
- Semaphore
- Thread
- Wartebarer Timer
Beispiele
Ein Beispiel finden Sie unter Verwenden von Mutex-Objekten.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | synchapi.h (enthalten Windows.h unter Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 Windows Server 2008 R2) |
| Bibliothek | Kernel32.lib |
| DLL | Kernel32.dll |