WaitForSingleObjectEx-Funktion (synchapi.h)

  • Artikel

Wartet, bis sich das angegebene Objekt im signalierten Zustand befindet, bis eine E/A-Vervollständigungsroutine oder ein asynchroner Prozeduraufruf (APC) für den Thread in die Warteschlange eingereiht wird oder das Timeoutintervall verstreicht.

Um auf mehrere Objekte zu warten, verwenden Sie 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 undefiniert.

Das Handle muss über das Synchronize-Zugriffsrecht verfügen. Weitere Informationen finden Sie unter Standardzugriffsrechte.

[in] dwMilliseconds

Das Timeoutintervall in Millisekunden. Wenn ein Nichtzerowert angegeben wird, wartet die Funktion, bis das Objekt signalisiert wird, eine E/A-Vervollständigungsroutine oder APC in die Warteschlange eingereiht wird oder das Intervall verstreicht. Wenn dwMilliseconds null ist, gibt die Funktion keinen Wartezustand auf, wenn die Kriterien nicht erfüllt sind. Es wird immer sofort zurückgegeben. Wenn dwMillisecondsUNENDLICH ist, wird die Funktion nur zurückgegeben, wenn das Objekt signalisiert oder eine E/A-Vervollständigungsroutine oder APC in eine Warteschlange gestellt 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.

[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-Vervollständigungsroutine oder APC in die Warteschlange stellt und der Thread die Routine oder Funktion ausführt. Andernfalls wird die Funktion nicht zurückgegeben, und die Vervollständigungsroutine oder APC-Funktion wird nicht ausgeführt.

Eine Vervollständigungsroutine 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 Vervollständigungsroutine wird nur aufgerufen, wenn bAlertableTRUE ist, und der aufrufende Thread der Thread ist, der den Lese- oder Schreibvorgang initiiert hat. Beim Aufrufen von QueueUserAPC wird ein APC in eine Warteschlange gestellt.

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, dem das Mutex-Objekt gehört, bevor der besitzereigene Thread beendet wurde. Der Besitz des Mutex-Objekts wird dem aufrufenden Thread gewährt, und der Mutex wird auf nicht signalisiert festgelegt.

Wenn der Mutex Informationen zu persistenten Zustanden schützt, sollten Sie ihn auf Konsistenz überprüfen.
WAIT_IO_COMPLETION
0x000000C0L
 Die Wartezeit wurde durch einen oder mehrere asynchrone Prozeduraufrufe im Benutzermodus beendet, die in die Warteschlange des Threads eingereiht wurden.
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 WaitForSingleObjectEx-Funktion 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 Zustand einiger Typen von Synchronisierungsobjekten. Die Änderung erfolgt nur für das Objekt, dessen signalisierter Zustand die Funktion zurückgegeben hat. Beispielsweise wird die Anzahl eines Semaphorobjekts um eins verringert.

Die WaitForSingleObjectEx-Funktion kann auf die folgenden Objekte warten:

  • Änderungsbenachrichtigung
  • Konsoleneingabe
  • Ereignis
  • Benachrichtigung zu Speicherressourcen
  • 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 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 zum Deadlocking 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 WaitForSingleObjectEx.

Beispiele

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

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 (einschließlich 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

Wartefunktionen