WaitForSingleObject

The WaitForSingleObject function specifies a timeout interval that is the interval duration and waits, in the alertable wait portion of the calling thread's execution, for an object to be in the signaled state by one of the following methods.

DWORD WaitForSingleObject(
                  HANDLE hHandle,
                  DWORD dwMilliseconds
                );

Parameters

Parameter	Description
`hHandle`	A handle to the object. For a list of object types whose handles can be specified, see the following Remarks section. The handle must have the `SYNCHRONIZE` access right.
`dwMilliseconds`	The time-out interval in milliseconds. If this parameter is zero, the function returns immediately. If this parameter is `INFINITE`, the function's time-out interval is the system-wide serverd time-out value. If this parameter is non-zero, the function waits for at least the specified number of milliseconds before returning, even if the object's state is signaled.

Return Value

If the function succeeds, the return value is one of the following values:

WAIT_OBJECT_0: The state of the specified object is signaled.
WAIT_TIMEOUT: The time-out interval elapsed and the object's state is not signaled.
WAIT_ABANDONED: The specified object is a mutex object and the previous owner exited without releasing the mutex. The function sets the mutex state to signaled and returns WAIT_ABANDONED.

If the function fails, the return value is WAIT_FAILED. To get extended error information, call GetLastError.

Remarks

The WaitForSingleObject function returns when one of the following occurs:

The specified object is in the signaled state.
The time-out interval elapses.

The hHandle parameter can be a handle to any of the following synchronization objects:

Change notification
Event
A mutex
A semaphore
A process
A thread
A job
A file

The object specified by hHandle must have its SYNCHRONIZE access right. For more information, see Synchronization Object Security and Access Rights.

If dwMilliseconds is INFINITE, the thread is suspended indefinitely until the object is signaled.

If dwMilliseconds is 0, the function checks the signaled state of the object and returns immediately.

To wait for multiple objects, use the WaitForMultipleObjects function.

In alertable wait functions, system-time intervals are reduced by the amount of time the thread spends in kernel mode. This is a very small amount of time.