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 排队时返回。
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 函数报告的结果是指定句柄的最后一个重叠操作的结果，该操作的结果是挂起的。 启动操作的函数返回 FALSE，GetLastError 函数返回 ERROR_IO_PENDING时，指示挂起的操作。 当 I/O 操作挂起时，启动该操作的函数会将 OVERLAPPED 结构的 hEvent 成员重置为非对齐状态。 然后，当挂起的操作完成时，系统会将事件对象设置为已发出信号的状态。
在 OVERLAPPED 结构中指定手动重置事件对象。 如果使用自动重置事件对象，则不得在启动重叠操作和调用 GetOverlappedResultEx 之间的间隔内在任何其他等待操作中指定事件句柄。 例如，事件对象有时在等待函数之一中指定，以等待操作完成。 当 wait 函数返回时，系统会将自动重置事件的状态设置为“未对齐”，而对 GetOverlappedResultEx 的后续调用（将 dwMilliseconds 参数设置为 INFINITE ）会导致无限期阻止该函数。
如果 OVERLAPPED 结构的 hEvent 成员为 NULL，则系统使用 hFile 句柄的状态在操作完成时发出信号。 不建议出于此目的使用文件、命名管道或通信设备句柄。 使用事件对象更安全，因为在同一文件、命名管道或通信设备上执行多个同时重叠操作时，可能会出现混淆。 在这种情况下，无法知道哪个操作导致对象状态被发出信号。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 8 [桌面应用 |UWP 应用] |
| 最低受支持的服务器 | Windows Server 2012 [桌面应用 |UWP 应用] |
| 目标平台 | Windows |
| 标头 | ioapiset.h (包括 Windows.h) |
| Library | Kernel32.lib |
| DLL | Kernel32.dll |