WSAGetOverlappedResult function
The WSAGetOverlappedResult function retrieves the results of an overlapped operation on the specified socket.函數返回指定套接字上的重疊操作的結果
Syntax
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 |
|---|---|
|
A successful WSAStartup call must occur before using this function. |
|
|
The network subsystem has failed. |
|
|
The descriptor is not a socket. |
|
|
The hEvent parameter of the WSAOVERLAPPED structure does not contain a valid event object handle. |
|
|
One of the parameters is unacceptable. |
|
|
The fWait parameter is FALSE and the I/O operation has not yet completed. |
|
|
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 |
|
|
Library |
|
|
DLL |
|