NTSTATUS
KeWaitForSingleObject(
IN PVOID Object,
IN KWAIT_REASON WaitReason,
IN KPROCESSOR_MODE WaitMode,
IN BOOLEAN Alertable,
IN PLARGE_INTEGER Timeout /* optional */
);
KeWaitForSingleObject puts the current thread into an alertable or nonalertable wait state until the given dispatcher object is set to the Signaled state or (optionally) until the wait times out.
KeWaitForSingleObject can return one of the following status values:
Value |
Meaning |
STATUS_SUCCESS |
The dispatcher object specified by the Object parameter satisfied the wait. |
STATUS_ALERTED |
The wait was completed because of an alert to the thread. |
STATUS_USER_APC |
A user APC was delivered to the current thread before the specified Timeout interval expired. |
STATUS_TIMEOUT |
A time-out occurred before the object was set to Signaled. This value can be returned when an explicit time-out value of zero is specified and the specified set of wait conditions cannot be immediately met. |
The current state of the specified Object is examined to determine whether the wait can be satisfied immediately. If so, the necessary side effects are performed on the object. Otherwise, the current thread is put in a waiting state and a new thread is selected for execution on the current processor.
The Alertable parameter specifies whether the thread can be alerted in the wait state. If the value of this parameter is TRUE and the thread is alerted for a mode that is equal to or more privileged than the given WaitMode, the thread’s wait will be satisfied with a completion status of STATUS_ALERTED.
If the WaitMode parameter is UserMode and the Alertable parameter is TRUE, the thread can also be awakened to deliver a user-mode APC. Kernel-mode APCs always cause the subject thread to be awakened if the wait IRQL is PASSIVE_LEVEL and no kernel APC is in progress.
If no Timeout is supplied, the calling thread will remain in a Wait state until the Object is signalled.
A Timeout of zero allows the testing of a set of wait conditions and for conditionally performing any side effects if the wait can be immediately satisfied, as in the acquisition of a mutex.
Callers of KeWaitForSingleObject must be running at IRQL <= DISPATCH_LEVEL. Usually, the caller must be running at IRQL PASSIVE_LEVEL and in a nonarbitrary thread context. A call while running at IRQL DISPATCH_LEVEL is valid if and only if the caller specifies a Timeout of zero. That is, a driver must not wait for a nonzero interval at IRQL DISPATCH_LEVEL.
ExInitializeFastMutex, KeBugCheckEx, KeInitializeEvent, KeInitializeMutex, KeInitializeSemaphore, KeInitializeTimer, KeWaitForMultipleObjects, KeWaitForMutexObject