ZwWaitForSingleObject-Funktion (ntifs.h)

Artikel
12/21/2024

Die ZwWaitForSingleObject Routine wartet, bis das angegebene Objekt den Status "Signaled" erreicht. Ein optionales Timeout kann auch angegeben werden.

Syntax

NTSYSAPI NTSTATUS ZwWaitForSingleObject(
  [in]           HANDLE         Handle,
  [in]           BOOLEAN        Alertable,
  [in, optional] PLARGE_INTEGER Timeout
);

Parameter

[in] Handle

Ein Handle für das Objekt.

[in] Alertable

Ein boolescher Wert, der angibt, ob die Wartezeit warnbar ist.

[in, optional] Timeout

Ein optionaler Zeiger auf einen Timeoutwert, der die absolute oder relative Uhrzeit angibt, zu der die Wartezeit abgeschlossen werden soll. Ein negativer Wert gibt ein Intervall relativ zur aktuellen Uhrzeit an. Der Wert sollte in Einheiten von 100 Nanosekunden ausgedrückt werden. Absolute Ablaufzeiten verfolgen alle Änderungen in der Systemzeit. Relative Ablaufzeiten sind von Systemzeitänderungen nicht betroffen.

Rückgabewert

ZwWaitForSingleObject kann einen der folgenden möglichen Statuscodes zurückgeben:

Rückgabecode	Beschreibung
STATUS_ACCESS_DENIED	Der Aufrufer verfügte nicht über die erforderlichen Berechtigungen für das vom Handle Parameter angegebene Ereignis.
STATUS_ALERTED	Die Wartezeit wurde abgebrochen, um eine Warnung an den aktuellen Thread zu übermitteln.
STATUS_INVALID_HANDLE	Der angegebene Handle Parameter war ungültig.
STATUS_SUCCESS	Das angegebene Objekt hat die Wartezeit erfüllt.
STATUS_TIMEOUT	Ein Timeout ist aufgetreten, bevor das Objekt auf einen signalgesteuerten Zustand festgelegt wurde. Dieser Wert kann zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann und der Timeout Parameter auf Null festgelegt ist.
STATUS_USER_APC	Die Wartezeit wurde abgebrochen, um einen Benutzer-APC an den aktuellen Thread zu übermitteln.

Beachten Sie, dass das NT_SUCCESS Makro die STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT und STATUS_USER_APC Statuswerte als "Erfolgswerte" erkennt.

Bemerkungen

ZwWaitForSingleObject wartet, bis das angegebene Objekt den Status "Signaled" erreicht. Ein optionales Timeout kann auch angegeben werden. ZwWaitForSingleObject untersucht den aktuellen Zustand des angegebenen Objekts, um festzustellen, ob die Wartezeit sofort erfüllt werden kann. Wenn ja, werden Aktionen ausgeführt. Andernfalls wird der aktuelle Thread in einen Wartezustand versetzt, und ein neuer Thread wird für die Ausführung auf dem aktuellen Prozessor ausgewählt.

Wenn kein Timeout- Parameter angegeben ist, wird die Wartezeit erst erfüllt, wenn das Objekt den Status "Signaled" erreicht. Wenn ein Timeout--Parameter angegeben ist und das Objekt keinen Status "Signaled" erreicht hat, wenn das Timeout abläuft, wird die Wartezeit automatisch erfüllt. Wenn ein expliziter Timeout Wert null angegeben ist, tritt keine Wartezeit auf, wenn die Wartezeit nicht sofort erfüllt werden kann. Ein Timeout Wert null ermöglicht das Testen einer Reihe von Wartezeitbedingungen und für die bedingte Leistung von Nebenwirkungen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Erwerb eines Mutex. Die Wartezeit kann auch als warnbar angegeben werden.

Der parameter Alertable gibt an, ob der Thread benachrichtigt werden kann, und der Wartezustand wird daher abgebrochen. Wenn der Wert dieses Parameters FALSCH ist, kann der Thread nicht benachrichtigt werden. Die einzige Ausnahme von dieser Regel ist die eines beendeten Threads. Unter bestimmten Umständen kann ein Beendigungsthread benachrichtigt werden, während er sich im Prozess des Abwickelns befindet. Ein Thread wird z. B. automatisch benachrichtigt, wenn ein Benutzer mit STRG+C beendet wird.

Wenn der Wert von AlertableWAHR ist und eine der folgenden Bedingungen vorhanden ist, wird der Thread benachrichtigt:

Wenn der Ursprung der Warnung eine interne, nicht dokumentierte Kernelmodusroutine ist, die für Warnungsthreads verwendet wird.
Der Ursprung der Warnung ist ein Benutzermodus-APC.

In den ersten dieser beiden Fälle ist die Wartezeit des Threads mit einem Abschlussstatus von STATUS_ALERTED zufrieden. Im zweiten Fall ist es mit einem Abschlussstatus von STATUS_USER_APC zufrieden.

Der Thread muss warnungsfähig sein, damit ein Benutzermodus-APC zugestellt werden kann. Dies ist nicht der Fall für Kernelmodus-APCs. Ein Kernelmodus-APC kann bereitgestellt und ausgeführt werden, obwohl der Thread nicht benachrichtigt wird. Sobald die Ausführung des APC abgeschlossen ist, wird die Wartezeit des Threads fortgesetzt. Ein Thread wird weder durch die Übermittlung eines Kernelmodus-APC benachrichtigt noch seine Wartezeit abgebrochen.

Die Übermittlung von Kernelmodus-APCs an einen Wartethread hängt nicht davon ab, ob der Thread benachrichtigt werden kann. Wenn der Kernelmodus-APC ein spezieller Kernelmodus-APC ist, wird der APC bereitgestellt, sofern die IRQL kleiner als APC_LEVEL ist. Wenn der Kernelmodus-APC ein normaler Kernelmodus-APC ist, wird der APC bereitgestellt, vorausgesetzt, dass die folgenden drei Bedingungen enthalten sind: (1) die IRQL ist kleiner als APC_LEVEL, (2) kein Kernel-APC wird ausgeführt, und (3) der Thread befindet sich nicht in einem kritischen Abschnitt.

Wenn sich der an ZwWaitForSingleObject übergebene Handle auf einen Mutex bezieht, entspricht die APC-Übermittlung für alle anderen Dispatcherobjekte während der Wartezeit. Sobald ZwWaitForSingleObject jedoch mit STATUS_SUCCESS zurückgegeben wird und der Thread tatsächlich den Mutex enthält, werden nur spezielle Kernelmodus-APCs bereitgestellt. Die Übermittlung aller anderen APCs, sowohl vom Kernelmodus als auch vom Benutzermodus, ist deaktiviert. Diese Einschränkung für die Bereitstellung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

Es ist besonders wichtig, den Rückgabewert von ZwWaitForSingleObject zu überprüfen, wenn der Parameter Alertable WAHR ist, da ZwWaitForSingleObject- möglicherweise frühzeitig mit einem Status von STATUS_USER_APC oder STATUS_ALERTED zurückgegeben werden.

Alle langfristigen Wartezeiten können von einem Benutzer abgebrochen werden, wenn der Parameter Alertable auf FALSE festgelegt ist.

Weitere Informationen finden Sie unter Empfangen von Wartethreads Warnungen und APCs?

Aufrufer von ZwWaitForSingleObject- müssen unter IRQL ausgeführt werden, die kleiner oder gleich DISPATCH_LEVEL sind. Normalerweise muss der Aufrufer bei IRQL-PASSIVE_LEVEL und in einem nichtarbiträren Threadkontext ausgeführt werden. Ein Aufruf bei der Ausführung bei IRQL DISPATCH_LEVEL ist gültig, wenn und nur, wenn der Aufrufer einen Timeout Parameter null angibt. Das heißt, ein Treiber darf nicht auf ein Nonzero-Intervall bei IRQL warten, das DISPATCH_LEVEL entspricht.

Timeoutintervalle werden relativ zur Systemuhr gemessen, und die Genauigkeit der Timeoutmessung ist durch die Granularität der Systemuhr begrenzt. Weitere Informationen finden Sie unter Zeitgebergenauigkeit.

Wenn der Aufruf der ZwWaitForSingleObject--Funktion im Benutzermodus auftritt, sollten Sie den Namen "NtWaitForSingleObject" anstelle von "ZwWaitForSingleObject" verwenden.

Bei Aufrufen von Kernelmodustreibern können sich die NtXxx und ZwXxx- Versionen einer Windows Native System Services-Routine anders verhalten, wie sie Eingabeparameter behandeln und interpretieren. Weitere Informationen zur Beziehung zwischen den NtXxx und ZwXxx- Versionen einer Routine finden Sie unter Using Nt and Zw Versions of the Native System Services Routines.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP
Zielplattform-	Universal
Header-	ntifs.h (einschließlich Ntifs.h, FltKernel.h)
Library	NtosKrnl.lib
DLL-	NtosKrnl.exe
IRQL-	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), SpNoWait(storport)