WaitForSingleObject-Funktion (synchapi.h)
Wartet, bis sich das angegebene Objekt im signalgesteuerten Zustand befindet oder das Timeoutintervall verstrichen ist.
Um einen warnbaren Wartezustand einzugeben, verwenden Sie die WaitForSingleObjectEx--Funktion. 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 nicht definiert.
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 oder das Intervall verstrichen ist. Wenn dwMilliseconds null ist, gibt die Funktion keinen Wartezustand ein, wenn das Objekt nicht signalisiert ist; es wird immer sofort zurückgegeben. Wenn dwMillisecondsINFINITEist, wird die Funktion nur zurückgegeben, wenn das Objekt signalisiert 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.
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.
| Zurückgeben von Code/Wert | Beschreibung |
|---|---|
|
Das angegebene Objekt ist ein Mutex-Objekt, das nicht vom Thread freigegeben wurde, der das Mutex-Objekt besitzt, bevor der eigene Thread beendet wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex-Zustand wird auf nichtsignaliert festgelegt.
Wenn der Mutex beständige Zustandsinformationen schützt, sollten Sie dies auf Konsistenz überprüfen. |
|
Der Zustand des angegebenen Objekts wird signalisiert. |
|
Das Timeoutintervall ist abgelaufen, und der Zustand des Objekts ist nicht signallos. |
|
Fehler bei der Funktion. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten. |
Bemerkungen
Die WaitForSingleObject-Funktion überprüft den aktuellen Status 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 Status einiger Synchronisierungsobjekte. Die Änderung erfolgt nur für das Objekt, dessen signalisierter Zustand dazu führte, dass die Funktion zurückgegeben wurde. Beispielsweise wird die Anzahl eines Semaphorobjekts um ein Objekt verringert.
Die funktion WaitForSingleObject kann auf die folgenden Objekte warten:
- Änderungsbenachrichtigung
- Konsoleneingabe
- Ereignis
- Speicherressourcenbenachrichtigung
- Mutex
- Prozess
- Semaphor
- Faden
- Wartezeitgeber
Beispiele
Ein Beispiel finden Sie unter Verwenden von Mutex-Objekten.
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 |