MFC WaitForSingleObject函数

Waits until the specified object is in the signaled state or the time-out interval elapses.
【等待，直到指定的对象处于信号状态或超时间隔结束。】
To enter an alertable wait state, use the WaitForSingleObjectEx function. To wait for multiple objects, use the WaitForMultipleObjects.
【要进入可报警的等待状态，请使用WaitForSingleObjectEx函数。要等待多个对象，请使用WaitForMultipleObjects。】

Syntax

DWORD WINAPI WaitForSingleObject(
  __in  HANDLE hHandle,
  __in  DWORD dwMilliseconds
);

Parameters

hHandle	A handle to the object. For a list of the object types whose handles can be specified, see the following Remarks section. 【对象的句柄。有关可以指定其句柄的对象类型的列表，请参见下面的备注部分。】 If this handle is closed while the wait is still pending, the function’s behavior is undefined. 【如果此句柄在等待仍挂起时关闭，则函数的行为未定义。】 The handle must have the SYNCHRONIZE access right. For more information, see Standard Access Rights. 【句柄必须具有同步访问权限。有关详细信息，请参阅标准访问权限。】
dwMilliseconds	The time-out interval, in milliseconds. The function returns if the interval elapses, even if the object’s state is nonsignaled. If dwMilliseconds is zero, the function tests the object’s state and returns immediately. If dwMilliseconds is INFINITE, the function’s time-out interval never elapses. 超时间隔，以毫秒为单位。如果间隔已过，则函数返回，即使对象的状态为非信号状态。如果dwmillizes为零，函数将测试对象的状态并立即返回。如果dwms是无限的，则函数的超时时间间隔永远不会过去。

Return Value

If the function succeeds, the return value indicates the event that caused the function to return. It can be one of the following values.
【如果函数成功，则返回值指示导致函数返回的事件。它可以是以下值之一。】

Return code/value	Description
WAIT_ABANDONED 0x00000080L	The specified object is a mutex object that was not released by the thread that owned the mutex object before the owning thread terminated. Ownership of the mutex object is granted to the calling thread, and the mutex is set to nonsignaled. 指定的对象是一个互斥对象，在拥有该互斥对象的线程终止之前，该对象没有被拥有该互斥对象的线程释放。互斥对象的所有权被授予调用线程，互斥被设置为nonsignaled。 If the mutex was protecting persistent state information, you should check it for consistency. 如果互斥体是在保护持久状态信息，则应该检查其一致性。
WAIT_OBJECT_0 0x00000000L	The state of the specified object is signaled. 【指定对象的状态被通知。】
WAIT_TIMEOUT 0x00000102L	The time-out interval elapsed, and the object’s state is nonsignaled. 【超时间隔已过，并且对象的状态为非信号状态。】

If the function fails, the return value is WAIT_FAILED ((DWORD)0xFFFFFFFF). To get extended error information, call GetLastError.
如果函数失败，则返回值为WAIT_FAILED （（DWORD）0xFFFFFFFF）。要获取扩展错误信息，请调用GetLastError。

Remarks

The WaitForSingleObject function checks the current state of the specified object. If the object’s state is nonsignaled, the calling thread enters the wait state until the object is signaled or the time-out interval elapses.
【WaitForSingleObject函数检查指定对象的当前状态。如果对象的状态为nonsignaled，则调用线程将进入wait状态，直到对象收到信号或超时间隔结束。】

The function modifies the state of some types of synchronization objects. Modification occurs only for the object whose signaled state caused the function to return. For example, the count of a semaphore object is decreased by one.
【此函数用于修改某些类型的同步对象的状态。只对其信号状态导致函数返回的对象进行修改。例如，信号量对象的计数减少1。】

The WaitForSingleObject function can wait for the following objects:
【WaitForSingleObject函数可以等待以下对象：】

• Change notification 【更改通知】
• Console input 【控制台输入】
• Event 【事件】
• Memory resource notification【内存资源通知】
• Mutex 【互斥量】
• Process 【进程】
• Semaphore 【信号量】
• Thread 【线程】
• Waitable timer 【可等待的计时器 】

Use caution when calling the wait functions and code that directly or indirectly creates windows. If a thread creates any windows, it must process messages. Message broadcasts are sent to all windows in the system. A thread that uses a wait function with no time-out interval may cause the system to become deadlocked. Two examples of code that indirectly creates windows are DDE and the CoInitialize function. Therefore, if you have a thread that creates windows, use MsgWaitForMultipleObjects or MsgWaitForMultipleObjectsEx, rather than WaitForSingleObject.
【在调用直接或间接创建窗口的等待函数和代码时要小心。如果线程创建任何窗口，它必须处理消息。消息广播发送到系统中的所有窗口。使用无超时间隔的等待函数的线程可能会导致系统死锁。间接创建窗口的两个代码示例是DDE和CoInitialize函数。因此，如果有创建窗口的线程，请使用MsgWaitForMultipleObjects或MsgWaitForMultipleObjectsEx，而不是WaitForSingleObject。】

用法小结