WSPGetOverlappedResult function
WSPGetOverlappedResult returns the results of an asynchronous (overlapped) operation on a socket. This operation previously indicated that it was pending completion.
Syntax
BOOL WSPGetOverlappedResult(
_In_ SOCKET s,
_In_ LPWSAOVERLAPPED lpOverlapped,
_Out_ LPDWORD lpcbTransfer,
_In_ BOOL fWait,
_Out_ LPDWORD lpdwFlags,
_Out_ LPINT lpErrno
);
Parameters
s [in]
Descriptor that identifies the socket. The switch specified this socket when it called the SAN service provider's WSPRecv, WSPSend, WSPRdmaRead, WSPRdmaWrite, or WSPIoctl function to start the overlapped operation.lpOverlapped [in]
Pointer to a WSAOVERLAPPED structure that the switch specified when it started the overlapped operation.lpcbTransfer [out]
Pointer to a variable that receives the number of bytes that were actually transferred by a send or receive operation, or by WSPIoctl.fWait [in]
Boolean value that is TRUE to specify that WSPGetOverlappedResult must wait for the pending overlapped operation to complete before returning; and FALSE to specify that if the overlapped operation is still pending, WSPGetOverlappedResult must return FALSE and, at lpErrno, WSA_IO_INCOMPLETE.lpdwFlags [out]
Pointer to a variable that receives one or more flags that supplement the completion status. If the switch called WSPRecv to initiate the overlapped operation, lpdwFlags receives the results value for the flags that were specified in the WSPRecv call.lpErrno [out]
Pointer to a variable that receives the error code.
Return value
Returns TRUE if successful; otherwise, returns FALSE and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAENOTSOCK | Descriptor is not a socket. |
| WSA_INVALID_HANDLE | The hEvent member of the WSAOVERLAPPED structure does not contain a valid handle to an event object. |
| WSA_INVALID_PARAMETER | One of the parameters is unacceptable. |
| WSA_IO_INCOMPLETE | The I/O operation has not yet completed. The SAN service provider can only return this error if the switch passed FALSE to the fWait parameter. |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPGetOverlappedResult function to obtain the results of an overlapped (asynchronous) operation that was previously started on a specific socket, but not completed. The results reported are those of the specified socket's last overlapped operation to which the specified pointer to a WSAOVERLAPPED structure was provided, and for which the operation's results were pending. The switch can call the WSPRecv, WSPRdmaRead, WSPSend, WSPRdmaWrite, or WSPIoctl function to start an overlapped operation on a socket. These functions can return SOCKET_ERROR and the WSA_IO_PENDING error code to indicate that an overlapped operation started and that completion of that operation occurs later. If an I/O operation is pending, the function that started the operation can call the Win32 ResetEvent function to reset the hEvent member of the WSAOVERLAPPED structure to the nonsignaled state. After the pending operation completes, the operating system sets the event object to the signaled state.
If the switch set fWait to TRUE, WSPGetOverlappedResult blocks and waits for the event object to be set to the signaled state to determine whether the pending overlapped operation completed. The switch can set fWait to TRUE only if it also selected event-based completion notification when it requested the I/O operation. If another form of notification was selected, the usage of the hEvent member of the WSAOVERLAPPED structure is different, and setting fWait to TRUE causes unpredictable results.
If WSPGetOverlappedResult returns TRUE, the overlapped operation completed successfully and the SAN service provider updated the value at lpcbTransfer. If WSPGetOverlappedResult returns FALSE, one of the following occurred:
The overlapped operation did not complete.
The overlapped operation completed, but with errors.
Completion status could not be determined due to errors in one or more parameters passed to WSPGetOverlappedResult.
On failure, the SAN service provider does not update the value at lpcbTransfer and sets the value at lpErrno to indicate the cause of the failure. Either WSPGetOverlappedResult or the associated overlapped operation can be the cause of the failure.
Interaction with WPUCompleteOverlappedRequest
The behavior of the WPUCompleteOverlappedRequest function places some constraints on how a SAN service provider implements WSPGetOverlappedResult. This is because only the Offset and OffsetHigh members of the WSAOVERLAPPED structure are exclusively controlled by the SAN service provider, even though the SAN service provider's WSPGetOverlappedResult function must retrieve three values (byte count, flags, and error) from the structure. A SAN service provider can retrieve these three values any way it chooses, as long as it interacts with the behavior of WPUCompleteOverlappedRequest properly. The following sequence presents a typical implementation:
At the start of an I/O operation, the SAN service provider sets the Internal member of the WSAOVERLAPPED structure to WSS_OPERATION_IN_PROGRESS.
After the I/O operation is complete, the SAN service provider performs the following actions:
- Sets OffsetHigh to the Windows Sockets error code resulting from the I/O operation.
- Sets Offset to the flags resulting from the I/O operation.
- Calls WPUCompleteOverlappedRequest and passes the number of bytes transferred.
WPUCompleteOverlappedRequest eventually sets the InternalHigh member of the WSAOVERLAPPED structure to the number of bytes transferred and then sets Internal to a value other than WSS_OPERATION_IN_PROGRESS.
After the switch calls the SAN service provider's WSPGetOverlappedResult function, the SAN service provider checks the value in Internal. If the value is WSS_OPERATION_IN_PROGRESS, the SAN service provider waits for the event object ( hEvent member) to be set to the signaled state or it returns an error, based on the value that the switch passed to fWait. If the value is not WSS_OPERATION_IN_PROGRESS, or after the operating system signals the event object, the SAN service provider returns the number of bytes transferred, operation result error code, and flags in the InternalHigh, OffsetHigh, and Offset members respectively.
For more information about WPUCompleteOverlappedRequest, see the Microsoft Windows SDK documentation.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also