WaitForSingleObject-Funktion (synchapi.h)

  • Artikel

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
WAIT_ABANDONED
0x00000080L
 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.
WAIT_OBJECT_0
0x00000000L
 Der Zustand des angegebenen Objekts wird signalisiert.
WAIT_TIMEOUT
0x00000102L
 Das Timeoutintervall ist verstrichen, und der Zustand des Objekts ist nicht signalisiert.
WAIT_FAILED
(DWORD)0xFFFFFFFF
 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
Gehen Sie vorsichtig vor, wenn Sie die Wartefunktionen und den Code aufrufen, der direkt oder indirekt Fenster erstellt. Wenn ein Thread Fenster erstellt, muss er Meldungen verarbeiten. Nachrichtenübertragungen werden an alle Fenster im System gesendet. Ein Thread, der eine Wartefunktion ohne Timeoutintervall verwendet, kann dazu führen, dass das System zu einem Deadlock wird. Zwei Beispiele für Code, der indirekt Fenster erstellt, sind DDE und die CoInitialize-Funktion . Wenn Sie über einen Thread verfügen, der Fenster erstellt, verwenden Sie daher MsgWaitForMultipleObjects oder MsgWaitForMultipleObjectsEx anstelle von WaitForSingleObject.

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

Siehe auch

Synchronisierungsfunktionen

Wait-Funktionen