getOverlappedResultEx 函数 (ioapiset.h)
检索指定超时间隔内对指定文件、命名管道或通信设备执行重叠操作的结果。 调用线程可以执行可警报等待。
语法
BOOL GetOverlappedResultEx(
[in] HANDLE hFile,
[in] LPOVERLAPPED lpOverlapped,
[out] LPDWORD lpNumberOfBytesTransferred,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
参数
[in] hFile
文件、命名管道或通信设备的句柄。 此句柄与通过调用 ReadFile、WriteFile、ConnectNamedPipe、TransactNamedPipe、DeviceIoControl 或 WaitCommEvent 函数启动重叠操作时指定的句柄相同。
[in] lpOverlapped
指向在启动重叠操作时指定的 OVERLAPPED 结构的指针。
[out] lpNumberOfBytesTransferred
指向变量的指针,该变量接收读取或写入操作实际传输的字节数。 对于 TransactNamedPipe 操作,这是从管道中读取的字节数。 对于 DeviceIoControl 操作,这是设备驱动程序返回的输出数据的字节数。 对于 ConnectNamedPipe 或 WaitCommEvent 操作,此值未定义。
[in] dwMilliseconds
超时间隔(以毫秒为单位)。
如果 dwMilliseconds 为零且操作仍在进行中,则函数将立即返回, GetLastError 函数返回 ERROR_IO_INCOMPLETE。
如果 dwMilliseconds 为非零值且操作仍在进行中,则函数将等到发出对象信号、I/O 完成例程或 APC 排队,或者经过间隔后再返回。 使用 GetLastError 获取扩展错误信息。
如果 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 函数完成时排队。 函数返回 ,并且仅当 bAlertable 为 TRUE 且调用线程是启动读取或写入操作的线程时,才会调用完成例程。 调用 QueueUserAPC 时,APC 将排队。
返回值
如果该函数成功,则返回值为非零值。
如果函数失败,则返回值为零。 要获得更多的错误信息,请调用 GetLastError。 常见错误代码包括:
- 如果 dwMilliseconds 为零且操作仍在进行中, 则 GetLastError 返回 ERROR_IO_INCOMPLETE。
- 如果 dwMilliseconds 不为零,并且 I/O 完成例程或 APC 已排队, 则 GetLastError 返回 WAIT_IO_COMPLETION。
- 如果 dwMilliseconds 为非零值且指定的超时间隔已过, 则 GetLastError 返回 WAIT_TIMEOUT。
注解
GetOverlappedResultEx 函数与 GetOverlappedResult 在以下方面有所不同:dwMilliseconds 参数可以指定操作的超时间隔,bAlertable 参数可以指定调用线程应执行可警报等待。
GetOverlappedResultEx 函数报告的结果是指定句柄的最后一个重叠操作的结果,其中提供了指定的 OVERLAPPED 结构,并且操作的结果处于挂起状态。 当启动操作的函数返回 FALSE 且 GetLastError 函数返回 ERROR_IO_PENDING时,指示挂起的操作。 当 I/O 操作挂起时,启动该操作的函数会将 OVERLAPPED 结构的 hEvent 成员重置为未签名状态。 然后,当挂起的操作完成时,系统将事件对象设置为信号状态。
在 OVERLAPPED 结构中指定手动重置事件对象。 如果使用自动重置事件对象,则不得在启动重叠操作和调用 GetOverlappedResultEx 之间的间隔内,在任何其他等待操作中指定事件句柄。 例如,事件对象有时在等待操作完成的等待函数之一中指定。 当 wait 函数返回时,系统会将自动重置事件的状态设置为非签名,并且随后调用将 dwMilliseconds 参数设置为 INFINITE 的 GetOverlappedResultEx 会导致函数无限期阻塞。
如果 OVERLAPPED 结构的 hEvent 成员为 NULL,则系统使用 hFile 句柄的状态在操作完成时发出信号。 不建议出于此目的使用文件、命名管道或通信设备句柄。 使用事件对象更安全,因为在同一文件、命名管道或通信设备上执行多个同时重叠操作时可能会出现混淆。 在这种情况下,无法知道哪个操作导致对象状态被发出信号。
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows 8 [桌面应用 |UWP 应用] |
最低受支持的服务器 | Windows Server 2012 [桌面应用 |UWP 应用] |
目标平台 | Windows |
标头 | ioapiset.h (包括 Windows.h) |
Library | Kernel32.lib |
DLL | Kernel32.dll |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈