Share via


recv

A version of this page is also available for

Windows Embedded CE 6.0 R3

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

See Also

Reference

accept (Windows Sockets)
bind (Windows Sockets)
connect (Windows Sockets)
ioctlsocket
recvfrom
select
send
sendto
shutdown
socket (Windows Sockets)
WSAAccept
WSAConnect
WSAEventSelect
WSAGetLastError
WSAIoctl
WSARecv
WSASendTo
WSAStartup