WaitForSingleObject

DWORD WaitForSingleObject(hObject, dwTimeout)
HANDLE hObject;	/* object to wait for	*/
DWORD dwTimeout;	/* timeout time in milliseconds	*/

The WaitForSingleObject function waits until the specified object is in the signaled state.

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 object is in the signaled state.

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.
0xFFFFFFFF	An error occurred. Use the GetLastError function to obtain extended error information.

Comments

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 WaitForSingleObject 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.