WSARecvEx

Notice This function is a Microsoft-specific extension to the Windows Sockets specification. For more information, see Microsoft Extensions and Windows Sockets 2.

The Windows Sockets WSARecvEx function is identical to the recv function, except the flags parameter is an in-out parameter. When a partial message is received while using datagram protocol, the MSG_PARTIAL bit is set in the flags parameter on return from the function.

int PASCAL FAR WSARecvEx (
  SOCKET s,         
  char FAR * buf,   
  int len,          
  int *flags        
);

Parameters

s: [in] A descriptor identifying a connected socket.
buf: [out] A buffer for the incoming data.
len: [in] The length of buf.
flags: [in/out] An indicator specifying whether the message is fully or partially received for datagram sockets.

Remarks

The WSARecvEx function that is part of the Microsoft implementation of Windows Sockets 2 is similar to the more common recv function except that the flags parameter is an in-out parameter, not just an in parameter. The additional out parameter is used to indicate whether a partial or complete message was received when a message-oriented protocol is being used.

The WSARecvEx and recv function identically for stream oriented protocols.

Making the flags parameter an in and out parameter accomodates two common situations in which a partial message will be received: when the application's data buffer size is smaller than the message size and the message coincidentally arrives in two pieces; and when the message is rather large and must arrive in several pieces. The MSG_PARTIAL bit is set in the flags parameter on return from WSARecvEx when a partial message was received. If a complete message was received, MSG_PARTIAL is not set in flags.

The Windows Sockets recv function is different than WSARecvEx in that the recv function always receives a single message for each call for message-oriented transport protocols. The recv function does not have a means to indicate to the application that the data received is only a partial message. An application must build its own protocol for checking whether a message is partial or complete by checking for the error code WSAEMSGSIZE after each call to recv. When the application buffer is smaller than the data being sent, as much of the message as will fit is copied into the user's buffer and recv returns with the error code WSAEMSGSIZE. A subsequent call to recv will get the next part of the message.

Applications written for message-oriented transport protocols should be coded for this possibility if message sizing is not guaranteed by the application's data transfer protocol. An application can use recv and manage the protocol itself. Alternatively, an applications can use WSARecvEx and check the for the MSG_PARTIAL bit is set in the flags parameter.

The WSARecvEx function provide the developer with a more effective way of checking whether a message received is partial or complete when a very large message arrives a little at a time. For example, if an application sends a 1-megabyte message, the transport protocol must break up the message in order to send it over the physical network. It is theoretically possible for the transport protocol on the receiving side to buffer all the data in the message, but this would be quite expensive in terms of resources. Instead, WSARecvEx can be used, minimizing overhead and eliminating the need for an application-based protocol.

Return Values

If no error occurs, WSARecvEx returns the number of bytes received. If the connection has been closed, it returns zero. Additionally, if a partial message was received, the MSG_PARTIAL bit is set in the flags parameter. If a complete message was received, MSG_PARTIAL is not set in flags.

Otherwise, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.

Important For a stream oriented transport protocol, MSG_PARTIAL is never set on return from WSARecvEx. This function behaves identically to the Windows Sockets recv function for stream transport protocols.

Error Codes

WSANOTINITIALISED	A successful WSAStartup must occur before using this function.
WSAENETDOWN	The network subsystem has failed.
WSAEFAULT	The buf parameter is not completely contained in a valid part of the user address space.
WSAENOTCONN	The socket is not connected.
WSAEINTR	The (blocking) call was canceled through WSACancelBlockingCall.
WSAEINPROGRESS	A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.
WSAENETRESET	The connection has been broken due to the remote host resetting.
WSAENOTSOCK	The descriptor is not a socket.
WSAEOPNOTSUPP	MSG_OOB was specified, but the socket is not stream-style such as type SOCK_STREAM, out-of-band data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations.
WSAESHUTDOWN	The socket has been shut down; it is not possible to use WSARecvEx on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH.
WSAEWOULDBLOCK	The socket is marked as nonblocking and the receive operation would block.
WSAEINVAL	The socket has not been bound with bind, or an unknown flag was specified, or MSG_OOB was specified for a socket with SO_OOBINLINE enabled or (for byte stream sockets only) len was zero or negative.
WSAECONNABORTED	The virtual circuit was terminated due to a time-out or other failure. The application should close the socket as it is no longer usable.
WSAETIMEDOUT	The connection has been dropped because of a network failure or because the peer system failed to respond.
WSAECONNRESET	The virtual circuit was reset by the remote side executing a "hard" or "abortive" close. The application should close the socket as it is no longer usable. On a UDP datagram socket this error would indicate that a previous send operation resulted in an ICMP "Port Unreachable" message.

QuickInfo