getOverlappedResultEx 函数 (ioapiset.h)

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

语法

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

参数

[in] hFile

文件、命名管道或通信设备的句柄。 这是通过调用 ReadFileWriteFileConnectNamedPipe、TransactNamedPipeDeviceIoControlWaitCommEvent 函数启动重叠操作时指定的句柄。

[in] lpOverlapped

指向在启动重叠操作时指定的 OVERLAPPED 结构的指针。

[out] lpNumberOfBytesTransferred

指向变量的指针,该变量接收读取或写入操作实际传输的字节数。 对于 TransactNamedPipe 操作,这是从管道读取的字节数。 对于 DeviceIoControl 操作,这是设备驱动程序返回的输出数据的字节数。 对于 ConnectNamedPipeWaitCommEvent 操作,此值未定义。

[in] dwMilliseconds

超时间隔(以毫秒为单位)。

如果 dwMilliseconds 为零且操作仍在进行中,则函数将立即返回, GetLastError 函数返回 ERROR_IO_INCOMPLETE

如果 dwMilliseconds 为非零值且操作仍在进行中,则函数将等到对象发出信号、I/O 完成例程或 APC 排队,或间隔过后再返回。 使用 GetLastError 获取扩展错误信息。

如果 dwMillisecondsINFINITE,则函数仅在向对象发出信号或 I/O 完成例程或 APC 排队时返回。

dwMilliseconds 值不包括在低功耗状态下花费的时间。 例如,当计算机处于睡眠状态时,超时不会继续倒计时。

[in] bAlertable

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

完成指定它的 ReadFileExWriteFileEx 函数时,完成例程将排队。 仅当 bAlertableTRUE 且调用线程是启动读取或写入操作的线程时,函数才会返回并调用完成例程。 调用 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

另请参阅

CancelIo

ConnectNamedPipe

CreateEvent

DeviceIoControl

GetLastError

GetOverlappedResult

OVERLAPPED

重叠的输入和输出

ReadFile

同步函数

TransactNamedPipe

WaitCommEvent

WriteFile