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

WSABUF

WSAOVERLAPPED

WSPBind

WSPGetOverlappedResult

WSPRegisterMemory

WSPSocket

Send comments about this topic to Microsoft