recv (Compact 2013)
3/26/2014
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 Compact 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 Compact does not support IgnorePushBitOnReceives.
Requirements
Header |
winsock2.h |
Library |
Ws2.lib |
See Also
Reference
Socket Functions
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