Freigeben über

WaitForSingleObjectEx-Funktion (synchapi.h)

  • Artikel

Wartet, bis sich das angegebene Objekt im signalgesteuerten Zustand befindet, eine E/A-Vervollständigungsroutine oder ein asynchroner Prozeduraufruf (APC) im Thread in die Warteschlange gestellt wird oder das Timeoutintervall verstrichen ist.

Um auf mehrere Objekte zu warten, verwenden Sie die WaitForMultipleObjectsEx-.

Syntax

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

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 wird, 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 das Objekt signalisiert 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 gibt die Funktion nicht zurück, 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 bAlertableTRUEist, und der aufrufende Thread ist der Thread, 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.

Zurückgeben von Code/Wert Beschreibung
WAIT_ABANDONED
0x00000080L
 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 wird auf nichtsignaliert festgelegt.

Wenn der Mutex beständige Zustandsinformationen schützt, sollten Sie dies auf Konsistenz überprüfen.
WAIT_IO_COMPLETION
0x0000000C0L
 Die Wartezeit wurde durch einen oder mehrere Benutzermodus beendet, asynchrone Prozeduraufrufe (APC) in die Warteschlange des Threads eingereiht wurden.
WAIT_OBJECT_0
0x000000000L
 Der Zustand des angegebenen Objekts wird signalisiert.
WAIT_TIMEOUT
0x00000102L
 Das Timeoutintervall ist abgelaufen, und der Zustand des Objekts ist nicht signallos.
WAIT_FAILED
(DWORD-)0xFFFFFFFF
 Fehler bei der Funktion. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Die funktion WaitForSingleObjectEx 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.

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 WaitForSingleObjectEx kann auf die folgenden Objekte warten:

  • Änderungsbenachrichtigung
  • Konsoleneingabe
  • Ereignis
  • Speicherressourcenbenachrichtigung
  • Mutex
  • Prozess
  • Semaphor
  • Faden
  • Wartezeitgeber
Achten Sie beim Aufrufen der Wartefunktionen und des Codes, die direkt oder indirekt Fenster erstellt. Wenn ein Thread Fenster erstellt, muss er Nachrichten 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 inaktiv wird. Zwei Beispiele für Code, der indirekt Fenster erstellt, sind DDE und die CoInitialize-Funktion. Wenn Sie daher über einen Thread verfügen, der Fenster erstellt, verwenden Sie MsgWaitForMultipleObjects oder MsgWaitForMultipleObjectsEx, anstatt WaitForSingleObjectEx.

Beispiele

Ein Beispiel finden Sie unter Named Pipe Server Using Completion Routines.

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

Siehe auch

Synchronisierungsfunktionen

Wait Functions