recv

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function receives data from a connected socket.

Syntax

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

Parameters

s
[in] Descriptor identifying a connected socket.

buf
[out] Buffer for the incoming data.

len
[in] Length of the buf parameter.

flags
[in] Flag specifying the way in which the call is made.

Return Value

If no error occurs, this function returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError. The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call 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 socket was closed.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAENETRESET	The connection has been broken due to the keep-alive activity detecting a failure while the operation was in progress.
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 (OOB) 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 receive 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.
WSAEMSGSIZE	The message was too large to fit into the specified buffer and was truncated.
WSAEINVAL	The socket has not been bound with bind (Windows Sockets), an unknown flag was specified, 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 because it is no longer usable.

Remarks

This function is used to read incoming data on connection-oriented sockets or connectionless sockets. When using a connection-oriented protocol, the sockets must be connected before calling this function. When using a connectionless protocol, the sockets must be bound before calling this function.

The local address of the socket must be known. For server applications, use an explicit bind (Windows Sockets) function or an implicit accept (Windows Sockets) or WSAAccept function. Explicit binding is discouraged for client applications. For client applications, the socket can become bound implicitly to a local address using connect (Windows Sockets), WSAConnect, sendto, or WSASendTo.

For connected or connectionless sockets, the recv function restricts the addresses from which received messages are accepted. The function only returns messages from the remote address specified in the connection. Messages from other addresses are (silently) discarded.

For connection-oriented sockets (type SOCK_STREAM, for example), calling recv will return as much information as is currently available — up to the size of the buffer supplied. For connectionless sockets (type SOCK_DGRAM or other message-oriented sockets), data is extracted from the first enqueued datagram (message) from the destination address specified by the connect function.

If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram and recv generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP), the excess data is lost; for reliable protocols, the data is retained by the service provider until it is successfully read by calling recv with a large enough buffer.

If no incoming data is available at the socket, the recv function call blocks and waits for data to arrive according to the blocking rules defined for WSARecv with the MSG_PARTIAL flag not set unless the socket is nonblocking. In this case, a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select or WSAEventSelect functions can be used to determine when more data arrives.

If the socket is connection-oriented, the remote side has shut down the connection gracefully, and all data has been received, a recv function will complete immediately with zero bytes received. If the connection has been reset, a recv function will fail with the error WSAECONNRESET.

The flags parameter can be used to influence the behavior of the recv function invocation beyond the options specified for the associated socket. The following table shows flags in the default service provider that Windows Embedded CE does not support (although other providers might support them).

Value	Description
MSG_PEEK	Peeks at the incoming data. The data is copied into the buffer but is not removed from the input queue. The function then returns the number of bytes currently pending to receive.
MSG_OOB	Processes OOB data.

If a client application is run on a computer with a TCP/IP implementation that does not set the push bit on send operations, response delays may result. It is best to correct this on the client; however, IgnorePushBitOnReceives, was added to Afd.sys in Microsoft® Windows NT® 4.0 and Microsoft® Windows® 2000 to force it to treat all arriving packets as though the push bit were set. Windows Embedded CE does not support IgnorePushBitOnReceives.

For more inforamtion about IrDA support in Windows Embedded CE, see Infrared Communications.

Requirements

Header	winsock2.h
Library	Ws2.lib
Windows Embedded CE	Windows CE 1.0 and later
Windows Mobile	Windows Mobile Version 5.0 and later

Share via

recv

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Additional resources