LPWSPGETOVERLAPPEDRESULT 回调函数 (ws2spi.h)

项目
08/28/2023

LPWSPGetOverlappedResult 函数返回指定套接字上重叠操作的结果。

语法

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

参数

[in] s

标识套接字。这与通过调用 LPWSPRecv、LPWSPRecvFrom、LPWSPSend、LPWSPSendTo 或 LPWSPIoctl 启动重叠操作时指定的套接字相同。

[in] lpOverlapped

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

[out] lpcbTransfer

指向 32 位变量的指针，该变量接收实际通过发送或接收操作或 LPWSPIoctl 传输的字节数。

[in] fWait

指定函数是否应等待挂起的重叠操作完成。如果 为 TRUE，则函数在操作完成之前不会返回。如果 FALSE 且操作仍处于挂起状态，则函数返回 FALSE 并且 lpErrno 为WSA_IO_INCOMPLETE。仅当重叠操作选择了基于事件的完成通知时， fWait 参数才能设置为 TRUE 。

[out] lpdwFlags

指向 32 位变量的指针，该变量将接收一个或多个补充完成状态的标志。如果重叠操作是通过 LPWSPRecv 或 LPWSPRecvFrom 启动的，则此参数将包含 lpFlags 参数的结果值。

[out] lpErrno

指向错误代码的指针。

返回值

如果 LPWSPGetOverlappedResult 成功，则返回值为 TRUE。这意味着重叠操作已成功完成，并且 l克朗德 指向的值已更新。如果 LPWSPGetOverlappedResult 返回 FALSE，则表示重叠操作尚未完成或重叠操作已完成但存在错误，或者由于 LPWSPGetOverlappedResult 的一个或多个参数中的错误而无法确定完成状态。失败时， 不会更新 l克朗德 指向的值。 lpErrno 参数指示失败的原因 (LPWSPGetOverlappedResult 或关联的重叠操作) 。

错误代码	含义
WSAENETDOWN	网络子系统发生故障。
WSAENOTSOCK	：描述符不是套接字。
WSA_INVALID_HANDLE	WSAOverlapped 结构的 hEvent 成员不包含有效的事件对象句柄。
WSAEINVAL	其中一个参数是不可接受的。
WSA_IO_INCOMPLETE	fWait 参数为 FALSE，I/O 操作尚未完成。

注解

LPWSPGetOverlappedResult 函数报告的结果是指定套接字的最后一个重叠操作的结果，其中提供了指定的 WSAOverlapped 结构，并且操作的结果处于挂起状态。启动操作的函数返回SOCKET_ERROR，并且 WSA_IO_PENDING lpErrno 时，指示挂起的操作。当 I/O 操作挂起时，启动该操作的函数会将 WSAOVERLAPPED 结构的 hEvent 成员重置为非对齐状态。然后，当挂起的操作完成时，系统会将事件对象设置为已发出信号的状态。

如果 fWait 参数为 TRUE，LPWSPGetOverlappedResult 将通过阻止并等待事件对象处于信号状态来确定挂起操作是否已完成。仅当客户端在请求 I/O 操作时选择了基于事件的完成通知时，才可将 fWait 参数设置为 TRUE 。如果选择了另一种通知形式，则 WSAOverlapped 结构的 hEvent 成员的用法会有所不同，并且将 fWait 设置为 TRUE 会导致不可预知的结果。

注意

当给定线程退出时，将取消由给定线程启动的所有 I/O。对于重叠套接字，如果在操作完成之前关闭线程，挂起的异步操作可能会失败。有关详细信息 ，请参阅 ExitThread 。

与 WPUCompleteOverlappedRequest 交互

WPUCompleteOverlappedRequest 的行为对服务提供程序实现 LPWSPGetOverlappedResult 的方式存在一些限制，因为即使 LPWSPGetOverlappedResult 必须从结构中检索三个值 (字节计数、标志和错误) ，WSAOverlappedResult 也只能控制 WSAOverlapped 结构的 Offset 和 OffsetHigh 成员。只要服务提供商正确与 WPUCompleteOverlappedRequest 的行为交互，它可以选择的任何方式来实现此目的。以下说明提供了一个典型的实现：

在重叠处理开始时，服务提供商将 Internal 设置为 WSS_OPERATION_IN_PROGRESS。

完成 I/O 操作后，提供程序将 OffsetHigh 设置为操作产生的 Windows 套接字 2 错误代码，将 Offset 设置为 I/O 操作生成的标志，并调用 WPUCompleteOverlappedRequest，将传输字节计数作为参数之一传递。 WPUCompleteOverlappedRequest 最终将 InternalHigh 设置为传输字节计数，然后将 Internal 设置为 WSS_OPERATION_IN_PROGRESS 以外的值。

调用 LPWSPGetOverlappedResult 时，服务提供商将检查“内部”。如果WSS_OPERATION_IN_PROGRESS，则提供程序将等待 hEvent 成员中的事件句柄，或者根据 LPWSPGetOverlappedResult 的 fWait 标志的设置返回错误。如果未进行或等待完成后，提供程序将分别返回 InternalHigh、 OffsetHigh 和 Offset 中的值作为传输计数、操作结果错误代码和标志。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	ws2spi.h