WinUsb_GetOverlappedResult 函数 (winusb.h)

项目
03/13/2024

WinUsb_GetOverlappedResult函数检索对指定文件执行的重叠操作的结果。

语法

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

参数

[in] InterfaceHandle

设备上第一个接口的不透明句柄，由 WinUsb_Initialize 返回。

[in] lpOverlapped

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

[out] lpNumberOfBytesTransferred

指向变量的指针，该变量接收读取或写入操作实际传输的字节数。

[in] bWait

如果此参数为 TRUE，则函数在操作完成之前不会返回。如果此参数为 FALSE 且操作仍处于挂起状态，则函数返回 FALSE，GetLastError 函数返回ERROR_IO_INCOMPLETE。

返回值

如果函数成功，则返回值为除零以外的任何数字。如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

此函数与 Win32 API 例程 GetOverlappedResult 类似，但有一个区别，调用方传递从 WinUsb_Initialize 返回的接口句柄，而不是传递从 CreateFile 返回的文件句柄。如果传递了相应的句柄，调用方可以使用任一 API 例程。 WinUsb_GetOverlappedResult 函数从接口句柄中提取文件句柄，然后调用 GetOverlappedResult。

WinUsb_GetOverlappedResult函数报告的结果是指定句柄的最后一个重叠操作中提供指定 OVERLAPPED 结构的结果，以及操作结果挂起的结果。当启动操作的函数返回 FALSE，并且 GetLastError 例程返回ERROR_IO_PENDING时，指示挂起的操作。当 I/O 操作挂起时，启动该操作的函数会将 OVERLAPPED 结构的 hEvent 成员重置为未签名状态。然后，当挂起的操作完成时，系统将事件对象设置为信号状态。

调用方可以指定在 OVERLAPPED 结构中手动重置事件对象。如果使用自动重置事件对象，则不得在启动重叠操作和调用WinUsb_GetOverlappedResult之间的间隔内，在任何其他等待操作中指定事件句柄。例如，事件对象有时在等待操作完成的某个等待例程中指定。当等待例程返回时，系统会将自动重置事件的状态设置为未签名，并且连续调用将 bWait 参数设置为 TRUE 的WinUsb_GetOverlappedResult会导致函数无限期地被阻止。

如果 bWait 参数为 TRUE， 则WinUsb_GetOverlappedResult 通过等待事件对象处于信号状态来确定挂起的操作是否已完成。

如果 OVERLAPPED 结构的 hEvent 成员为 NULL，则系统使用文件句柄的状态在操作完成时发出信号。请勿将文件句柄用于此目的。最好使用事件对象，因为对同一文件执行多个并发重叠操作时可能会出现混淆。在这种情况下，你无法知道哪个操作导致对象状态被发出信号。