WaitForSingleObject 函数 (synchapi.h)

  • 项目

等待指定的对象处于信号状态或超时间隔已过。

若要进入可警报等待状态，请使用 WaitForSingleObjectEx 函数。 若要等待多个对象，请使用 WaitForMultipleObjects。

语法

DWORD WaitForSingleObject(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds
);

参数

[in] hHandle

对象的句柄。 有关可以指定其句柄的对象类型的列表，请参阅以下“备注”部分。

如果在等待仍处于挂起状态时关闭此句柄，则函数的行为未定义。

句柄必须具有 SYNCHRONIZE 访问权限。 有关详细信息，请参阅 标准访问权限。

[in] dwMilliseconds

超时间隔（以毫秒为单位）。 如果指定了非零值，则函数将等待，直到发出对象信号或间隔已过。 如果 dwMilliseconds 为零，则如果未向对象发出信号，则函数不会进入等待状态;它始终立即返回。 如果 dwMilliseconds 为 INFINITE，则函数仅在发出对象信号时返回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2：dwMilliseconds 值包括在低功率状态下花费的时间。 例如，当计算机处于睡眠状态时，超时也会持续倒计时。

Windows 8、Windows Server 2012、Windows 8.1、Windows Server 2012 R2、Windows 10和Windows Server 2016：dwMilliseconds 值不包括在低功率状态下花费的时间。 例如，当计算机处于睡眠状态时，超时会暂停倒计时。

返回值

如果函数成功，则返回值指示导致函数返回的事件。 可以是下列值之一。

返回代码/值 说明
WAIT_ABANDONED
0x00000080L
 指定的 对象是一个互斥对象，在拥有的线程终止之前，拥有互斥对象对象的线程未释放该互斥对象。 互斥对象的所有权授予调用线程，互斥体状态设置为非签名。

如果互斥体正在保护永久性状态信息，则应检查它以确保一致性。
WAIT_OBJECT_0
0x00000000L
 指定对象的状态已发出信号。
WAIT_TIMEOUT
0x00000102L
 超时间隔已过，并且对象的状态未对齐。
WAIT_FAILED
(DWORD) 0xFFFFFFFF
 函数失败。 要获得更多的错误信息，请调用 GetLastError。

注解

WaitForSingleObject 函数检查指定对象的当前状态。 如果对象的状态未对齐，则调用线程将进入等待状态，直到发出对象信号或超时间隔已过。

函数修改某些类型的同步对象的状态。 仅针对其信号状态导致函数返回的对象进行修改。 例如，信号量对象的计数将减少 1。

WaitForSingleObject 函数可以等待以下对象：

  • 更改通知
  • 控制台输入
  • 事件
  • 内存资源通知
  • Mutex
  • 进程
  • Semaphore
  • 线程
  • 可等待计时器
调用直接或间接创建窗口的等待函数和代码时请谨慎。 如果线程创建任何窗口，它必须处理消息。 消息广播将发送到系统中的所有窗口。 使用没有超时间隔的等待函数的线程可能会导致系统死锁。 间接创建窗口的两个代码示例是 DDE 和 CoInitialize 函数。 因此，如果你有创建窗口的线程，请使用 MsgWaitForMultipleObjects 或 MsgWaitForMultipleObjectsEx，而不是 WaitForSingleObject。

示例

有关示例，请参阅 使用互斥体对象。

要求

   
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 synchapi.h (包括 Windows Server 2003 上的 Windows.h、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2)
Library Kernel32.lib
DLL Kernel32.dll

另请参阅

同步函数

等待函数