WSAGetOverlappedResult

WSAGetOverlappedResult function

The WSAGetOverlappedResult function retrieves the results of an overlapped operation on the specified socket.函数返回指定套接字上的重叠操作的结果

Syntax

C++

BOOL WSAAPI WSAGetOverlappedResult(
  _In_   SOCKET s,
  _In_   LPWSAOVERLAPPED lpOverlapped,
  _Out_  LPDWORD lpcbTransfer,
  _In_   BOOL fWait,
  _Out_  LPDWORD lpdwFlags
);

Parameters

s [in]

A descriptor identifying the socket.套接字。

This is the same socket that was specified when the overlapped operation was started by a call to any of the Winsock functions that supports overlappped operations. These functions includeAcceptEx,ConnectEx,DisconnectEx,TransmitFile, TransmitPackets, WSARecv, WSARecvFrom, WSARecvMsg, WSASend, WSASendMsg, WSASendTo, and WSAIoctl.之前调用了WSAOVERLAPPED结构的函数使用过的那个套接字。这些函数包括：blablabla。

lpOverlapped [in]

A pointer to a WSAOVERLAPPED structure that was specified when the overlapped operation was started. This parameter must not be aNULL pointer.指向之前重叠操作所用的那个WSAOVERLAPPED结构体。本参数不能为NULL。

lpcbTransfer [out]

A pointer to a 32-bit variable that receives the number of bytes that were actually transferred by a send or receive operation, or by theWSAIoctl function. This parameter must not be a NULL pointer.通过send、receive或者WSAIoctl函数实际发送的字节数。本参数不能为NULL。

fWait [in]

A flag that specifies whether the function should wait for the pending overlapped operation to complete. If TRUE, the function does not return until the operation has been completed. IfFALSE and the operation is still pending, the function returns FALSE and the WSAGetLastError function returns WSA_IO_INCOMPLETE. The fWait parameter may be set to TRUE only if the overlapped operation selected the event-based completion notification.一个是否等待重叠操作完成的标志。为TRUE时，直到操作完成函数才会返回。如果设置为FALSE而且错做仍旧未完成，那么函数会返回FALSE，并且WSAGetLastError函数会返回WSA_IO_INCOMPLETE。只有当重叠操作选择的是基于事件的完成通知时，才会使用TRUE值。

lpdwFlags [out]

A pointer to a 32-bit variable that will receive one or more flags that supplement the completion status. If the overlapped operation was initiated throughWSARecv or WSARecvFrom, this parameter will contain the results value for lpFlags parameter. This parameter must not be aNULL pointer.指向完成状态标志。如果重叠操作是由WSARecv或者WSARecvFrom发起的，这个参数会包含lpFlags的结果值。本参数不能为NULL。

Return value

If WSAGetOverlappedResult succeeds, the return value is TRUE. This means that the overlapped operation has completed successfully and that the value pointed to bylpcbTransfer has been updated.成功返回TRUE。这表示重叠操作成功完成，并且会更新lpcbTransfer的值。

If WSAGetOverlappedResult returns FALSE, this means that either the overlapped operation has not completed, the overlapped operation completed but with errors, or the overlapped operation's completion status could not be determined due to errors in one or more parameters to WSAGetOverlappedResult. On failure, the value pointed to by lpcbTransfer will not be updated. UseWSAGetLastError to determine the cause of the failure (either by theWSAGetOverlappedResult function or by the associated overlapped operation).如果返回FALSE，表示重叠操作没有完成，或者完成但出错，或者由于参数错误导致无法确定重叠操作是否完成。如果函数操作失败，就不会更新lpcbTransfer参数。使用WSAGetLastError来确定出错原因。

Error code	Meaning
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAENOTSOCK	The descriptor is not a socket.
WSA_INVALID_HANDLE	The hEvent parameter of the WSAOVERLAPPED structure does not contain a valid event object handle.
WSA_INVALID_PARAMETER	One of the parameters is unacceptable.
WSA_IO_INCOMPLETE	The fWait parameter is FALSE and the I/O operation has not yet completed.
WSAEFAULT	One or more of the lpOverlapped, lpcbTransfer, or lpdwFlags parameters are not in a valid part of the user address space. This error is returned if thelpOverlapped,lpcbTransfer, orlpdwFlags parameter was aNULL pointer on Windows Server 2003 and earlier.

 

Remarks

The WSAGetOverlappedResult function reports the results of the overlapped operation specified in thelpOverlapped parameter for the socket specified in thes parameter. The WSAGetOverlappedResult function is passed the socket descriptor and theWSAOVERLAPPED structure that was specified when the overlapped function was called. A pending operation is indicated when the function that started the operation returnsFALSE and theWSAGetLastError function returns WSA_IO_PENDING. When an I/O operation such as WSARecv is pending, the function that started the operation resets the hEvent member of theWSAOVERLAPPED structure to the nonsignaled state. Then, when the pending operation has completed, the system sets the event object to the signaled state.函数报告lpOverlapped中指定的套接字的重叠操作结果。函数传递了之前重叠操作中指定的套接字和WSAOVERLAPPED结构。未完成的操作是指发起操作的函数返回了FALSE，并且调用WSAGetLastError函数返回了WSA_IO_PENDING。当类似于WSARecv的IO操作未完成时，发起操作的函数重置WSAOVERLAPPED中的hEvent为无信号状态。然后当未完成的操作最终完成时，系统设置事件对象为有信号状态。

If the fWait parameter is TRUE, WSAGetOverlappedResult determines whether the pending operation has been completed by waiting for the event object to be in the signaled state. A client may set the fWait parameter to TRUE, but only if it selected event-based completion notification when the I/O operation was requested. If another form of notification was selected, the usage of thehEvent parameter of theWSAOVERLAPPED structure is different, and setting fWait toTRUE causes unpredictable results.如果fWait为TRUE，函数通过等待事件对象为有信号来决定是否未完成的操作已经完成。客户端可能设置fWait为TRUE，但仅在请求IO操作时选用以事件为基础的完成通知。如果采用其他的通知方式，WSAOVERLAPPED中hEvent的用法可能不同，设置为TRUE会引起不可预测的结果。

If the WSAGetOverlappedResult function is called with the lpOverlapped, lpcbTransfer, or lpdwFlags parameter set to a NULL pointer on Windows Vista, this will result in an access violation. If theWSAGetOverlappedResult function is called with the lpOverlapped,lpcbTransfer, or lpdwFlags parameter set to a NULL pointer on Windows Server 2003 and earlier, this will result in theWSAEFAULT error code being returned.在Vista中调用WSAGetOverlappedResult函数并将lpOverlapped、lpcbTransfer、lpdwFlags设为NULL时，会引起访问违规。但是同样的情形发生在2003或者更早的版本时，会返回WSAEFAULT错误。

Note   All I/O is canceled when a thread exits. For overlapped sockets, pending asynchronous operations can fail if the thread is closed before the operations complete. SeeExitThread for more information.当线程退出时，所有的I/O操作都会取消。对重叠的套接字来说，在线程退出前未完成的异步操作都会失败。

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client	Windows 8.1, Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Minimum supported phone	Windows Phone 8
Header	Winsock2.h
Library	Ws2_32.lib
DLL	Ws2_32.dll

See also

Winsock Reference Winsock Functions WSAAccept WSAConnect WSACreateEvent WSAIoctl WSARecv WSARecvFrom WSASend WSASendTo WSAWaitForMultipleEvents