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 为零,则如果不满足条件,函数不会进入等待状态;它始终会立即返回。 如果 dwMilliseconds 为 INFINITE,则仅当向对象发出信号或 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、Windows 8.1、Windows Server 2012 R2、Windows 10和Windows Server 2016:dwMilliseconds 值不包括在低功率状态下花费的时间。 例如,当计算机处于睡眠状态时,超时会暂停倒计时。
[in] bAlertable
如果此参数为 TRUE 且线程处于等待状态,则当系统将 I/O 完成例程或 APC 排队,并且线程运行例程或函数时,函数将返回 。 否则,该函数不会返回,并且不执行完成例程或 APC 函数。
完成例程在指定它的 ReadFileEx 或 WriteFileEx 函数完成时排队。 wait 函数返回,并且仅当 bAlertable 为 TRUE 且调用线程是启动读取或写入操作的线程时,才会调用完成例程。 调用 QueueUserAPC 时,APC 将排队。
返回值
如果函数成功,则返回值指示导致函数返回的事件。 可以是下列值之一。
返回代码/值 | 说明 |
---|---|
|
指定的对象是一个互斥对象,在拥有的线程终止之前,拥有 mutex 对象的线程未释放该对象。 互斥对象的所有权授予调用线程,互斥体设置为非签名。
如果互斥体正在保护永久性状态信息,则应检查它以确保一致性。 |
|
等待由一个或多个用户模式 异步过程调用 结束, (APC) 排队到线程。 |
|
指定对象的状态已发出信号。 |
|
超时间隔已过,并且对象的状态未对齐。 |
|
函数失败。 要获得更多的错误信息,请调用 GetLastError。 |
注解
WaitForSingleObjectEx 函数确定是否满足等待条件。 如果未满足条件,调用线程将进入等待状态,直到满足等待条件或超时间隔已过。
函数修改某些类型的同步对象的状态。 修改仅适用于其信号状态导致函数返回的对象。 例如,信号灯对象的计数将减少 1。
WaitForSingleObjectEx 函数可以等待以下对象:
- 更改通知
- 控制台输入
- 事件
- 内存资源通知
- Mutex
- 进程
- Semaphore
- 线程
- 可等待计时器
示例
有关示例,请参阅 命名管道服务器使用完成例程。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows XP [桌面应用 | UWP 应用] |
最低受支持的服务器 | Windows Server 2003 [桌面应用 | UWP 应用] |
目标平台 | Windows |
标头 | synchapi.h (包括 Windows Server 2003、Windows Vista、Windows 7、Windows Server 2008 Windows Server 2008 R2) |
Library | Kernel32.lib |
DLL | Kernel32.dll |