通过

WaitForSingleObjectEx 函数 （synchapi.h）

  • 项目

等待指定的对象处于信号状态、I/O 完成例程或异步过程调用（APC）排队到线程，或超时间隔已过。

若要等待多个对象，请使用 WaitForMultipleObjectsEx。

语法

DWORD WaitForSingleObjectEx(
  [in] HANDLE hHandle,
  [in] DWORD  dwMilliseconds,
  [in] BOOL   bAlertable
);

参数

[in] hHandle

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

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

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

[in] dwMilliseconds

超时间隔（以毫秒为单位）。 如果指定了非零值，函数将等待对象发出信号、I/O 完成例程或 APC 排队，或间隔运行。 如果 dwMilliseconds 为零，则如果未满足条件，则函数不会进入等待状态;它始终会立即返回。 如果 dwMillisecondsINFINITE，则仅当发出信号或 I/O 完成例程或 APC 排队时，函数才会返回。

Windows XP、Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 和 Windows Server 2008 R2：dwMilliseconds 值确实包括用于低功率状态的时间。 例如，当计算机处于睡眠状态时，超时确实会不断倒计时。

Windows 8 及更新版本、Windows Server 2012 及更新版本：dwMilliseconds 值不包括在低功率状态下花费的时间。 例如，当计算机处于睡眠状态时，超时不会不断倒计时。

[in] bAlertable

如果此参数 TRUE 且线程处于等待状态，则当系统排队 I/O 完成例程或 APC 时，该函数将返回，线程运行例程或函数。 否则，该函数不会返回，并且不会执行完成例程或 APC 函数。

ReadFileEx 或 WriteFileEx 函数（在其中指定了该例程已完成）时，完成例程将排队。 仅当 bAlertableTRUE，调用线程是启动读取或写入操作的线程时，才会返回等待函数并调用完成例程。 调用 QueueUserAPC时，APC 将排队。

返回值

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

返回代码/值 描述
WAIT_ABANDONED
0x00000080L
 指定的对象是一个互斥体对象，该对象不是由拥有互斥体对象的线程在拥有线程终止之前释放的。 mutex 对象的所有权授予调用线程，互斥体设置为非对齐。

如果互斥体保护持久状态信息，则应检查它是否一致性。
WAIT_IO_COMPLETION
0x000000C0L
 等待由一个或多个用户模式结束，异步过程调用（APC）排队到线程。
WAIT_OBJECT_0
0x00000000L
 指定对象的状态已发出信号。
WAIT_TIMEOUT
0x00000102L
 超时间隔已用，并且对象的状态不对齐。
WAIT_FAILED
（DWORD）0xFFFFFFFF
 函数失败。 若要获取扩展的错误信息，请调用 GetLastError。

言论

WaitForSingleObjectEx 函数确定是否满足等待条件。 如果条件尚未满足，则调用线程将进入等待状态，直到满足等待条件的条件或超时间隔已过。

该函数修改某些类型的同步对象的状态。 仅针对发出信号状态导致函数返回的对象进行修改。 例如，信号灯对象的计数减少一个。

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

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

例子

有关示例，请参阅 使用完成例程的命名管道服务器。

要求

要求 价值
最低支持的客户端 Windows XP [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2003 [桌面应用 |UWP 应用]
目标平台 窗户
标头 synchapi.h （包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2 上的 Windows.h）
库 Kernel32.lib
DLL Kernel32.dll

另请参阅

同步函数

等待函数