ZwWaitForSingleObject-Funktion (ntifs.h)

Artikel
07/11/2023

Die ZwWaitForSingleObject-Routine wartet, bis das angegebene Objekt den Status Signaled erreicht. Optional kann auch ein Timeout 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 warnungsfähig ist.

[in, optional] Timeout

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

Rückgabewert

ZwWaitForSingleObject kann einen der folgenden möglichen status Codes 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 Signalzustand festgelegt wurde. Dieser Wert kann zurückgegeben werden, wenn der angegebene Satz von Wartebedingungen nicht sofort erfüllt werden kann und der Timeoutparameter auf 0 festgelegt ist.
STATUS_USER_APC	Die Wartezeit wurde abgebrochen, um einen Benutzer-APC an den aktuellen Thread zu übermitteln.

Beachten Sie, dass das makro NT_SUCCESS die werte STATUS_ALERTED, STATUS_SUCCESS, STATUS_TIMEOUT und STATUS_USER_APC status als "success" werte erkennt.

Hinweise

ZwWaitForSingleObject wartet, bis das angegebene Objekt den Status Signaled erreicht. Optional kann auch ein Timeout angegeben werden. ZwWaitForSingleObject untersucht den aktuellen Zustand des angegebenen Objekts, um zu ermitteln, 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 Timeoutparameter angegeben wird, wird die Wartezeit nicht erfüllt, bis das Objekt den Status Signaled erreicht hat. Wenn ein Timeoutparameter angegeben wird und das Objekt den Status Signaled nicht erreicht hat, wenn das Timeout abläuft, wird die Wartezeit automatisch erfüllt. Wenn ein expliziter Timeoutwert von 0 angegeben wird, tritt keine Wartezeit auf, wenn die Wartezeit nicht sofort erfüllt werden kann. Ein Timeoutwert von 0 ermöglicht das Testen einer Reihe von Wartebedingungen und für die bedingte Leistung aller Nebenwirkungen, wenn die Wartezeit sofort erfüllt werden kann, wie beim Erwerb eines Mutex. Die Wartezeit kann auch als warnungsfähig angegeben werden.

Der Warnungsparameter gibt an, ob der Thread benachrichtigt werden kann und sein Wartezustand daher abgebrochen wird. Wenn der Wert dieses Parameters FALSE ist, kann der Thread nicht benachrichtigt werden. Die einzige Ausnahme von dieser Regel ist die eines beendenden Threads. Unter bestimmten Umständen kann ein beendender Thread benachrichtigt werden, während er sich gerade im Abwickeln befindet. Ein Thread wird automatisch für instance warnungsfähig gemacht, wenn er von einem Benutzer mit STRG+C beendet wird.

Wenn der Wert von AlertableTRUE ist und eine der folgenden Bedingungen vorliegt, wird der Thread benachrichtigt:

Wenn der Ursprung der Warnung eine interne, nicht dokumentierte Kernelmodusroutine ist, die zum Warnen von Threads verwendet wird.
Der Ursprung der Warnung ist ein Benutzermodus-APC.

Im ersten dieser beiden Fälle wird die Wartezeit des Threads mit einer status von STATUS_ALERTED abgeschlossen. Im zweiten Fall ist sie mit einer Status von STATUS_USER_APC zufrieden.

Der Thread muss warnungsfähig sein, damit ein Benutzermodus-APC übermittelt wird. Dies ist bei Kernelmodus-APCs nicht der Fall. Ein Kernelmodus-APC kann übermittelt 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 benachrichtigt, noch wird seine Wartezeit durch die Übermittlung eines Kernelmodus-APC abgebrochen.

Die Übermittlung von Kernelmodus-APCs an einen wartenden Thread hängt nicht davon ab, ob der Thread benachrichtigt werden kann. Wenn es sich bei dem Kernelmodus-APC um einen speziellen Kernelmodus-APC handelt, wird der APC bereitgestellt, sofern der IRQL kleiner als APC_LEVEL ist. Wenn es sich bei der Kernelmodus-APC um einen normalen Kernelmodus-APC handelt, wird der APC übermittelt, sofern die folgenden drei Bedingungen gelten: (1) der 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 das an ZwWaitForSingleObject übergebene Handle auf einen Mutex verweist, ist die APC-Übermittlung identisch mit allen anderen Dispatcherobjekten 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 im Kernelmodus als auch im Benutzermodus, ist deaktiviert. Diese Einschränkung für die Übermittlung von APCs bleibt bestehen, bis der Mutex freigegeben wird.

Es ist besonders wichtig, den Rückgabewert von ZwWaitForSingleObject zu überprüfen, wenn der Warnungsparameter TRUE ist, da ZwWaitForSingleObject möglicherweise frühzeitig mit einer status von STATUS_USER_APC oder STATUS_ALERTED zurückgegeben wird.

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

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

Aufrufer von ZwWaitForSingleObject müssen mit IRQL ausgeführt werden, die kleiner als oder gleich DISPATCH_LEVEL. In der Regel muss der Aufrufer bei IRQL PASSIVE_LEVEL und in einem nichtarbiträren Threadkontext ausgeführt werden. Ein Aufruf während der Ausführung bei IRQL DISPATCH_LEVEL ist nur gültig, wenn der Aufrufer einen Timeoutparameter von 0 angibt. Das heißt, ein Treiber darf nicht auf ein ungleiches Intervall bei IRQL warten, das DISPATCH_LEVEL entspricht.

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

Wenn der Aufruf der ZwWaitForSingleObject-Funktion im Benutzermodus erfolgt, 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, da sie Eingabeparameter verarbeiten und interpretieren. Weitere Informationen zur Beziehung zwischen den Nt Xxx- und ZwXxx-Versionen einer Routine finden Sie unter Verwenden von Nt- und Zw-Versionen der Systemdienstroutinen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h, FltKernel.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDDIs(storport), SpNoWait(storport)