WaitForSingleObjectEx

DWORD WaitForSingleObjectEx(hObject, dwTimeout, fAlertable)
HANDLE hObject;	/* object to wait for	*/
DWORD dwTimeout;	/* timeout time in milliseconds	*/
BOOL fAlertable;	/* return if I/O completes?	*/

The WaitForSingleObjectEx function waits until the specified object is in the signaled state or until an I/O callback function is called.

This function is available only in Win32/NT.

Parameters

hObject

Specifies an open handle to a waitable object. The handle must have SYNCHRONIZE access to the object.

dwTimeout

Specifies the number of milliseconds the function will wait for the object. If dwTimeout is zero, the function tests the object and returns immediately. If dwTimeout is INFINITE, the function will not return until the wait is satisfied.

fAlertable

Specifies whether the function may terminate early due to an I/O completion callback. If fAlertable is TRUE and the thread that called the WaitForSingleObjectEx function is the same thread that called the extended I/O function, then the wait can return due to any one of the wait termination conditions or because an I/O completion callback terminated the wait early (in this case, the return value is WAIT_IO_COMPLETION).

If fAlertable is FALSE, the function will not return when an I/O completion callback occurs.

Return Value

The following list shows the possible return values:

Value

Meaning

0	The specified object reached the signaled state and completed the wait.
WAIT_TIMEOUT	The wait was terminated because the timeout time was reached.
WAIT_ABANDONED	All of the following conditions are true: the specified object is a mutex object, the mutex object reached the signaled state, and the mutex object was abandoned.
WAIT_IO_COMPLETION	The wait terminated due to one or more I/O completion callbacks. (fAlertable must be TRUE and the thread that called this function must be the same thread that called the extended I/O function).
0xFFFFFFFF	An error occurred. Use the GetLastError function to obtain extended error information.

Comments

If fAlertable is FALSE, this function will not return until the specified time interval has passed, the object enters the signalled state, or the object is abandoned. If fAlertable is TRUE, the function may also return when an I/O completion callback occurs (the return value is WAIT_IO_COMPLETION).

Waiting on an object checks the current state of the object. If the current state of the object allows continued execution, any adjustments to the object state are made (for example, decrementing the semaphore count for a semaphore object) and the thread continues execution. If the current state of the object does not allow continued execution, the thread is placed into the wait state pending the change of the object's state or a timeout.

The WaitForSingleObjectEx function can wait for the following objects:

change notification

console input

event

file

mutex

process

thread

semaphore

For console input handles, the wait will be satisfied when at least one character is in the buffer.