WSPRecv function
WSPRecv receives data on a connected socket.
Syntax
int WSPRecv(
_In_ SOCKET s,
_Inout_ LPWSABUF lpBuffers,
_In_ DWORD dwBufferCount,
_Out_ LPDWORD lpNumberOfBytesRecvd,
_Inout_ LPDWORD lpFlags,
_In_ LPWSAOVERLAPPED lpOverlapped,
_In_ LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine,
_In_ LPWSATHREADID lpThreadId,
_Out_ LPINT lpErrno
);
Parameters
s [in]
Descriptor that identifies a connected socket.lpBuffers [in, out]
Pointer to an array of WSABUF structures. Each WSABUF structure describes a buffer. The switch registered each buffer in a previous call to the WSPRegisterMemory function.dwBufferCount [in]
Number of WSABUF structures at lpBuffers.lpNumberOfBytesRecvd [out]
Pointer to a variable that receives the number of bytes that WSPRecv received.lpFlags [in, out]
Pointer to a set of flags.lpOverlapped [in]
Pointer to a WSAOVERLAPPED structure that provides a communication medium between the initiation of an overlapped I/O operation and its subsequent completion. Ignored for nonoverlapped sockets.lpCompletionRoutine [in]
The switch always specifies NULL for lpCompletionRoutine. The SAN service provider therefore ignores lpCompletionRoutine. For information about how the provider can complete a pending receive request, see the Remarks section.lpThreadId [in]
The switch always specifies NULL for lpThreadId. The SAN service provider therefore ignores lpThreadId.lpErrno [out]
Pointer to a variable that receives the error code.
Return value
Returns zero if successful and the receive operation completed immediately; otherwise returns SOCKET_ERROR and, at lpErrno, one of the following error codes:
| Return code | Description |
|---|---|
| WSAENETDOWN | Network subsystem failed. |
| WSAENOTCONN | Socket is not connected. |
| WSAENETRESET | Connection has been broken due to keep-alive activity detecting a failure while the operation was in progress. |
| WSAEFAULT | The lpBuffers parameter is not totally contained in a valid part of the user address space. |
| WSAENOTSOCK | Descriptor is not a socket. |
| WSAESHUTDOWN | Socket has been shut down; it is not possible for the WSPRecv function to receive data on a socket after the socket has been shut down. |
| WSAEINVAL | The switch either did not create the socket with the overlapped flag or did not call the WSPBind function to bind the socket. |
| WSAECONNABORTED | The connection to the remote peer was terminated due to a time-out or other failure. |
| WSAECONNRESET | The connection was reset by the remote peer. |
| WSAEDISCON | The connection was gracefully closed by the remote peer. |
| WSA_IO_PENDING | The SAN service provider successfully initiated an overlapped receive operation and will indicate completion at a later time. |
| WSA_OPERATION_ABORTED | The overlapped operation was canceled because the socket was closed. |
Note that a SAN service provider does not support the following error codes for WSPRecv:
| Return code | Description |
|---|---|
| WSAEINTR | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEINPROGRESS | The Windows Sockets switch never issues cancel blocking calls to a SAN service provider. |
| WSAEOPNOTSUPP | The socket is the appropriate type. |
| WSAEWOULDBLOCK | The Windows Sockets switch uses overlapped sockets. |
| WSAEMSGSIZE | The current version of Windows Sockets Direct does not support SAN service providers handling sockets that receive datagrams. Also, broadcast addresses are not supported. |
Remarks
The Windows Sockets switch calls a SAN service provider's WSPRecv function to receive data on a connected socket. Before calling WSPRecv, the switch must have previously called the SAN service provider's WSPBind function to assign a local IP address to the specified socket. A SAN service provider receives WSPRecv requests from the switch--never directly from an application.
Typically during connection setup time, the switch calls the SAN service provider's WSPRegisterMemory extension function to preregister all memory for the buffer array that receives the incoming data.
The switch specifies an overlapped structure if the switch calls the SAN service provider's WSPRecv function in an overlapped manner. The switch calls the WSPRecv function to post one or more buffers that receive incoming data as the data becomes available. If the data reception operation cannot complete immediately, the operation proceeds, but WSPRecv returns with the WSA_IO_PENDING error code. The switch later calls the SAN service provider's WSPGetOverlappedResult function and passes a pointer to the overlapped structure to retrieve the final completion status.
The buffer array that the switch supplies in a WSPRecv call is a pointer to an array of WSABUF structures. The SAN service provider fills buffers in the order in which they appear in the buffer array and must pack buffers so as not to create holes in those buffers. The buffer array is transient. That is, if the WSPRecv call returns without completing the data reception operation, the SAN service provider must capture the pointer to the array of WSABUF structures before returning from WSPRecv. This requirement enables the switch to build stack-based buffer arrays.
The SAN service provider places incoming data into buffers until the SAN service provider fills those buffers, the switch closes the connection, or the SAN service provider exhausts internally buffered data. Regardless of whether the incoming data fills all the buffers, the SAN service provider signals a completion event for overlapped sockets.
If WSPRecv returns the WSAECONNRESET error code, the remote peer performed a hard close of the connection.
Overlapped Socket I/O
If the data reception operation completes immediately, the SAN service provider returns from WSPRecv with a value of zero and specifies the number of bytes received at lpNumberOfBytesRecvd. If the SAN service provider successfully initiated the data reception operation and will indicate completion at a later time, the SAN service provider returns from WSPRecv with a value of SOCKET_ERROR and specifies the WSA_IO_PENDING error code at lpErrno. Note that in this case, a value is not specified at lpNumberOfBytesRecvd and flags at lpFlags are not updated. After the data reception operation completes, the switch calls the SAN service provider's WSPGetOverlappedResult function and passes pointers to variables to hold data reception information and completion flags. The SAN service provider specifies the number of bytes received and completion flags in these pointers.
The overlapped structure at lpOverlapped must be valid for the duration of the data reception operation. If multiple data reception operations are outstanding simultaneously, each must reference a separate overlapped structure.
As mentioned previously, the switch always specifies an event in an overlapped structure if the switch calls the SAN service provider's WSPRecv function in an overlapped manner. The SAN service provider should call the WPUCompleteOverlappedRequest function in the context of an arbitrary thread to complete the data reception operation. If the low order bit of the hEvent member in the WSAOVERLAPPED structure is set, the switch specifically requests to not be notified upon completion of the data reception operation. Therefore, the SAN service provider is not required to call the WPUCompleteOverlappedRequest function to complete the I/O request. In this case, the switch calls the WSPGetOverlappedResult function to poll for completion. For more information, see the GetQueuedCompletionStatus function in the Microsoft Windows SDK documentation.
For more information about WPUCompleteOverlappedRequest, see the Windows SDK documentation.
The SAN service provider can deliver completion notifications in any order; the SAN service provider is not required to deliver notifications in the same order that overlapped operations are completed. However, the SAN service provider fills posted buffers with incoming data in the same order in which the switch supplies them.
Requirements
Target platform |
Desktop |
Version |
Requires Windows Sockets version 2.0. |
Header |
Ws2spi.h (include Ws2spi.h) |
See also