getOverlappedResultEx 函数 (ioapiset.h)

项目
08/24/2023

检索指定超时间隔内对指定文件、命名管道或通信设备执行重叠操作的结果。调用线程可以执行可警报等待。

语法

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